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.