Errors

Conceptual

Error envelope, codes and correct client handling.

Errors use a stable envelope. Route on type and code, never on the human-readable message.

json
{
  class="tok-str">"error": {
    class="tok-str">"type": class="tok-str">"invalid_request",
    class="tok-str">"code": class="tok-str">"capability_not_granted",
    class="tok-str">"message": class="tok-str">"Capability 'codebase.write' is not granted to this API key.",
    class="tok-str">"param": class="tok-str">"capabilities[class="tok-num">2]",
    class="tok-str">"request_id": class="tok-str">"req_8k2ld9",
    class="tok-str">"docs_url": class="tok-str">"https://docs.pimsy.ai/docs/tools/permissions"
  }
}
HTTPTypeClient action
400invalid_requestFix the request; do not retry unchanged
401authentication_errorCheck the key
403permission_deniedRequest the capability or adjust policy
404not_foundVerify the identifier and workspace
409conflictResource state changed; re-read and retry
422unprocessableSemantically invalid; fix the payload
429rate_limitedHonour Retry-After, back off
500internal_errorRetry with backoff; include request_id in reports
503service_unavailableRetry with backoff

Last updated 2026-09-15