Errors

The control-plane error envelope

Control-plane failures return a JSON body with a human message and a machine code:

{
  "message": "This entitlement has no remaining token quota.",
  "code": "insufficient_tokens"
}

Validation failures add an errors map keyed by field name:

{
  "message": "Please check the highlighted fields and try again.",
  "code": "validation_failed",
  "errors": {
    "email": ["This email is already registered."]
  }
}

code is stable and safe to compare against. message is copy: it is written for a human reading a screen, it can be reworded at any time, and it may be localised. Never branch on it, and never regex it.

Control-plane codes

Classified by the client

These three are produced by SP Cambo's own clients — this dashboard included — when a failure arrives without a usable code. They are not sent by the server, but you will see them in the UI and it is useful to know what they mean.

Handling them

const res = await fetch(url, { headers })

if (!res.ok) {
  const body = await res.json().catch(() => ({}))

  switch (body.code) {
    case 'insufficient_tokens':
    case 'insufficient_credits':
      return stopAndPromptForTopUp()      // never retry: the answer will not change
    case 'rate_limit_exceeded':
    case 'concurrency_limit_exceeded':
      return retryAfterBackoff(res.headers.get('retry-after'))
    case 'session_expired':
    case 'unauthenticated':
      return reauthenticate()
    default:
      throw new Error(body.message ?? 'Request failed')
  }
}

The important distinction is between retry and stop. A quota error will return the same answer however many times you send it, so retrying only burns your own rate limit. A 429 or a 5xx is worth retrying with backoff.

That example reads body.code, which is the control-plane shape. Inference failures put the code somewhere else — see below before reusing this against the gateway.

Errors from the inference gateway

Inference failures do not use the envelope above. They are shaped like the API you are calling, so your existing SDK error handling keeps working — which also means the SP Cambo code is in a different field depending on the surface. On /v1/messages and /v1/messages/count_tokens:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "The model does not support this inference protocol.",
    "sp_cambo_code": "model_unavailable"
  }
}

On /v1/responses, /v1/chat/completions and the key and model read endpoints:

{
  "error": {
    "message": "The model does not support this inference protocol.",
    "type": "invalid_request_error",
    "code": "model_unavailable"
  }
}

Read the code from error.sp_cambo_code on the first and error.code on the second. The type field is the upstream classification your SDK expects and is coarser than the code — several distinct SP Cambo failures share one type, so branch on the code.

Gateway codes

These are additional to the codes above; rate_limit_exceeded, insufficient_tokens, insufficient_credits, account_suspended and server_error also arrive here, meaning the same thing.

Every 4xx in the table is refused before any upstream call and is therefore not metered — a misconfigured client cannot quietly drain a package. The exception is upstream_rejected, which is the provider refusing the request itself; there the reservation is released, so it is not charged either. Where a request reached the provider and then failed part-way, the reservation is released or held for reconciliation rather than settled, so you are never charged an estimate for a response you did not receive.

For errors that appear mid-stream rather than in the status line, see streaming .

What errors never contain

Error bodies never include a stack trace, an internal hostname, an upstream provider identifier or a credential. If you are seeing a framework error page instead of one of these envelopes, you are not talking to SP Cambo — check the base URL and any proxy in between.