Errors
Every error is structured JSON with a code, a human message, and a machine-actionable resolution — built for agents that fix their own failures.
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_balance",
"message": "Your prepaid 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.
Reporting issues
Include the x-fabric-request-id response header — it identifies the exact request in our ledger and upstream traces.