Errors

Error shape

Errors never come back as bare strings. The resolution field says what to do next, retry, top up, switch models, in a form an agent can act on.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your balance is empty.",
    "resolution": "Top up at https://companyfabric.com/dashboard/billing or add a BYOK provider key at 0% fee."
  }
}

Payment required (402)

Gateway-billed keys with an empty balance receive HTTP 402 with the structured error above. Billing is post-paid by one request on purpose, a conversation is never cut off mid-reply.

A key that has reached its monthly budget cap also receives HTTP 402, with the code key_budget_exceeded, until the cap is raised or removed or the month rolls over.

Provider errors (400, 429, 502)

When the provider serving a model refuses a request as invalid, for example a prompt longer than the model's context window or a parameter the model does not take, you receive the provider's status (400, 413 or 422) with the code provider_rejected_request and the provider's own message. Sending the same body again gets the same answer, so change the request or the model.

A rate limit at the provider comes back as 429, and a provider that is down or failing as 502 with the code upstream_error, after any other route for the model has been tried. Either is worth retrying with backoff.

None of these is billed. Each one appears on your usage page with the provider's reason.

Reporting issues

Include the x-fabric-request-id response header, it identifies the exact request in our ledger and upstream traces.