Guides

Errors

Every failure has the same shape: an HTTP status, a stable type to branch on, and a sentence for a log or a person.

The shape

json

{
  "error": {
    "type": "invalid_api_key",
    "message": "That API key is not valid. It may have been revoked."
  }
}

Branch on type, not on message: the sentence may be reworded, the type will not. Every error response also carries Cache-Control: no-store.

Types

missing_api_key401: No bearer token on the request.
invalid_api_key401: The key is malformed, unknown or revoked.
insufficient_credits402: The balance would not cover the work.
budget_exceeded402: The account's own monthly ceiling was reached.
platform_budget_exceeded402: Paid work is paused on Corollary for the moment.
rate_limited429: Too many requests from this key or this address. Wait Retry-After seconds.
service_unavailable503: Something on our side did not answer — the ledger, the run store, the model. Nothing was charged; try again shortly.

Retrying

429 and 503 are worth retrying, after Retry-After or a few seconds respectively. 401 and 402 are not: the request will fail the same way until the key or the balance changes.

NextResearch runsAsk a question, follow the run, answer its questions, fetch its files.