Error contract
Every error response is { code, message, remediation, retryable, docs_url } with a stable code. Each code's docs_url links to its row here.
| Code | HTTP | Remediation |
|---|---|---|
| not_found | 404 | Check the digest or asset hash. Records are immutable and never move. |
| method_not_allowed | 405 | The registry is append-only: only GET and the public ingest POST exist. No PUT/DELETE. |
| payload_too_large | 413 | Reduce the record body. Artifacts live with their owners; records carry metadata only. |
| unsupported_media_type | 415 | Send Content-Type application/json (or the record media type) on ingest. |
| invalid_record | 422 | Validate against the published JSON Schema at /spec before signing. |
| digest_mismatch | 422 | digest must equal the sha256 of the exact bytes you signed. Recompute and resubmit. |
| signature_invalid | 401 | The signature did not verify against your registered key. Check key_id and the signing bytes. |
| unauthorized | 401 | Obtain a token from /oauth/token (client_credentials) and send it as a Bearer token. |
| forbidden | 403 | This action is not permitted for your tier or class. |
| insufficient_scope | 403 | Your token lacks the required publish:* scope. Verification requires review. |
| rate_limited | 429 | Slow down and honor Retry-After. Agents are customers: request a higher tier if you need more. |
| idempotency_conflict | 409 | This Idempotency-Key was used with a different request body. Use a fresh key. |
| validation_error | 422 | One or more fields failed validation. See message for the failing path. |
| conflict | 409 | The resource already exists in a conflicting state. |
| sealed | 451 | This record is sealed (takedown). Its digest, log position, and sealing event remain public. |
| payment_required | 402 | The action needs a plan, credits, or a higher monthly cap. The response lists prices and the routes to pay. Reading and verifying are always free. |
| sigstore_invalid | 422 | The record's Sigstore bundle did not verify against the pinned Sigstore trusted root. sigstore_check names the rule; fix the bundle or send the record without it. |
| model_behind | 503 | The world model has not read up to that checkpoint yet. Retry in a few seconds, or ask for an earlier as_of. |
| internal_error | 500 | An unexpected error occurred. The request may be retryable. |
$ curl -H 'Accept: application/json' https://aisourceoftruth.com/docs/errors # this page is a rendering of the API. Reproduce it as data.