Errors

Every failure — 4xx and 5xx alike — arrives in the same envelope. Parse it once.

The envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "brand_forbidden",
    "message": "You do not have access to this brand."
  }
}

A 422 adds an errors map, and nothing else changes:

{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "The request was invalid.",
    "errors": {
      "accounts": ["Select at least one social account."],
      "schedule_type": ["This field is required."]
    }
  }
}

Types

The catalog

Grouped by what you should do, which matters more than the number.

Fix the request — never retry

Money and plan limits — retrying will not help

A 402 always means the request was valid but your plan will not allow it. The code tells you which lever to pull.

Wait, then retry

Handling them

Branch on code, and let the categories drive the behaviour rather than writing a case per endpoint:

const NEVER_RETRY = new Set([
  'unauthorized', 'insufficient_scope', 'brand_forbidden',
  'test_mode_write_forbidden', 'invalid_request', 'not_found',
  'idempotency_key_required', 'idempotency_error', 'limit_reached',
  'feature_not_available', 'insufficient_credits', 'storage_limit_exceeded',
])

async function call(req, attempt = 1) {
  const res = await fetch(req)
  if (res.ok) return res.json()

  const { error } = await res.json()

  if (NEVER_RETRY.has(error.code)) {
    throw new ApiError(error)                 // a bug, or a billing decision — surface it
  }

  if (res.status === 429) {
    await sleep(Number(res.headers.get('Retry-After') ?? 5) * 1000)
    return call(req, attempt + 1)             // same Idempotency-Key: safe
  }

  if (res.status >= 500 && attempt < 4) {
    await sleep(2 ** attempt * 1000)
    return call(req, attempt + 1)
  }

  throw new ApiError(error)
}