Solved Docs

Errors

The RFC 9457 format, the code field, how to branch on it.

Every 4xx/5xx response is application/problem+json (RFC 9457):

{
  "type": "https://docs.solved.group/errors/insufficient_credits",
  "title": "Not enough credits",
  "status": 402,
  "detail": "This operation costs 43 credits; balance is 12.",
  "code": "insufficient_credits",
  "request_id": "req_01J9Z4A7R3V5W2XN4V6B0RTC5H",
  "retryable": false,
  "meta": { "required_credits": 43, "balance": 12 }
}

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:

"errors": [{ "field": "/destination_url", "code": "invalid_url", "detail": "Not a valid absolute URL." }]

Common codes you'll hit:

codeHTTPretryablemeaning
validation_failed422norequest body failed schema validation
unauthenticated401nomissing or invalid credential
insufficient_scope403nokey/session lacks the required scope
insufficient_credits402nonot enough balance; top up and retry
rate_limited429yesback off; see Retry-After
idempotency_in_progress409yesthe same key is mid-flight; retry shortly
idempotency_key_reused422nosame 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