Errors
Safe public error envelope and operation-specific codes.
Error body and correlation #
Code example
{
"error": {
"code": "SOME_CODE",
"message": "Safe message",
"details": {}
}
}The error body has no top-level request_id. Use the X-Request-Id: req_<UUIDv4> response header for correlation. Internal SQL, provider, and database errors are not public.
Public error matrix #
| HTTP | Applies to | Codes |
|---|---|---|
| 400 | Verification | INVALID_JSON, VALIDATION_ERROR |
| 400 | Reporting request validation | INVALID_JSON, VALIDATION_ERROR, INVALID_IDEMPOTENCY_KEY |
| 401 | All five operations | UNAUTHORIZED |
| 403 | All five operations | FORBIDDEN |
| 404 | Reporting status and evidence | REPORT_NOT_FOUND, EVIDENCE_NOT_FOUND |
| 409 | Applicable Reporting operations | IDEMPOTENCY_CONFLICT, PARTNER_REFERENCE_CONFLICT, EVIDENCE_LIMIT_EXCEEDED, UPLOAD_AUTHORIZATION_EXPIRED, EVIDENCE_NOT_UPLOADED, EVIDENCE_OBJECT_MISMATCH |
| 429 | Admission | RATE_LIMIT_EXCEEDED, MONTHLY_QUOTA_EXCEEDED |
| 500 | Commercial authentication/server setup | INTERNAL_ERROR |
| 500 | Verification | INTERNAL_SERVER_ERROR, LOOKUP_FAILED |
| 500 | Reporting | INTERNAL_ERROR |
| 503 | Authentication/admission | USAGE_ENFORCEMENT_UNAVAILABLE |
| 503 | Verification | RISK_DATA_UNAVAILABLE |
| 503 | Reporting | REPORTING_UNAVAILABLE, STORAGE_UNAVAILABLE, UPLOAD_AUTHORIZATION_UNAVAILABLE |
404 for missing, cross-client, or cross-environment Reporting resources is non-enumerating. Do not infer another organization's resource ownership.