API Errors and Problem Details
Handle Manifest AI API errors using RFC 9457 problem details, stable error codes, and request identifiers.
API v1 errors use application/problem+json. Branch on HTTP status and stable code, show detail only where appropriate, and log request_id for support and tracing.
Problem response
The response follows RFC 9457 and adds stable code and request_id extensions.
JSON
{
"type": "https://manifestai.io/docs/errors#document-not-found",
"title": "Document not found",
"status": 404,
"detail": "No document with this identifier is available in your workspace.",
"code": "DOCUMENT_NOT_FOUND",
"request_id": "8fd3476e-3d45-4ac2-8ea9-f4f13f651f08"
}Status handling
Use status class and error code together.
- 400 / 422
- Correct the request, mapping, or file before retrying.
- 401 / 403
- Fix the key, scope, workspace status, or plan entitlement.
- 404
- The resource does not exist or is not visible to this workspace.
- 409
- Resolve an idempotency, duplicate, or lifecycle conflict.
- 429
- Wait for Retry-After, then retry with jitter.
- 5xx
- Retry safe requests with exponential backoff and retain X-Request-Id.