Errors
The RFC 9457 format, the code field, how to branch on it.
Every 4xx/5xx response is application/problem+json (RFC 9457):
Branch on code, never on title or status alone. code is the one field we guarantee stable —
title is a human description and can be reworded. retryable tells you whether the same request with
the same Idempotency-Key is safe to resend. request_id matches the X-Request-ID header; include it
when asking us for help with a specific failure.
Validation errors add an errors[] array pointing at the bad field:
Common codes you'll hit:
| code | HTTP | retryable | meaning |
|---|---|---|---|
validation_failed | 422 | no | request body failed schema validation |
unauthenticated | 401 | no | missing or invalid credential |
insufficient_scope | 403 | no | key/session lacks the required scope |
insufficient_credits | 402 | no | not enough balance; top up and retry |
rate_limited | 429 | yes | back off; see Retry-After |
idempotency_in_progress | 409 | yes | the same key is mid-flight; retry shortly |
idempotency_key_reused | 422 | no | same key, different request body — use a new key |
Full registry, with every platform and per-product code: /errors (generated from the
spec — I2, SOL-6629).
On MCP, the same information comes back as a tool result with isError: true and a structuredContent
block (error_code, retry_eligible, message) instead of a protocol-level error — your agent sees the
failure and can react to it.
Next: Rate limits · Idempotency