Errors
RFC 9457 problem details, status handling, and retryability.
This guide shows you how to read a problem body, handle each HTTP status, and interpret errors on asynchronous resources.
Synchronous /api/v1alpha1 HTTP errors use Content-Type: application/problem+json and follow RFC 9457. HTTP 200 asynchronous resources use a nested error object with code, title, detail, and next_action; it has no HTTP status member.
Problem Body
{
"type": "https://developers.deepframe.cloud/errors/idempotency-in-flight",
"title": "Idempotency key is in use",
"status": 409,
"detail": "A request with this idempotency key is still being processed.",
"instance": "/api/v1alpha1/runs",
"request_id": "req_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"
}| Field | Use |
|---|---|
type | Stable problem URI. Branch client behavior on this value. |
title | Short human-readable summary. |
status | HTTP status code. |
detail | Sanitized explanation of this occurrence. |
instance | Request instance or route context. |
request_id | Correlation id for support and tracing. |
errors | Optional field-level validation details. |
admission_constant | Capability constant that rejected an analysis request. |
admitted_values | Values accepted by the named capability, when available. |
Handle By Status
- 400: Correct a malformed or schema-invalid request. Do not retry unchanged.
- 401: Correct the key or authentication header.
- 402: Wait for a quota or plan change.
- 403: Correct the permission, billing state, trial state, or workspace alpha opt-in. A valid key in a workspace that is not opted in receives this status with type
forbidden. - 404: Verify the resource id and key access.
- 409: Inspect the problem type. Wait for
idempotency-in-flightor wait for a conflicting resource state to change. - 422: Correct the input. Analysis admission failures identify the rejected capability in
admission_constant. - 429: Honor
Retry-Afterand the rate-limit headers. - 500: Retry only when the operation is safe to repeat.
- 503: Retry with bounded exponential backoff and jitter.
Keep Idempotency-Key On Retries
For a mutating POST, resend the same Idempotency-Key with the same body. A matching replay returns the original response. A different body returns 422 idempotency-payload-mismatch.
Asynchronous Resource Errors
Poll the resource status as before. When an asynchronous resource fails, use error.code for client behavior and error.next_action for the next step. The nested error is separate from status, result_state, reason_code, and limitations.
Example response:
{
"status": "failed",
"error": {
"code": "processing_failed",
"title": "Video processing failed",
"detail": "The video could not be processed.",
"next_action": "Upload the video again."
},
"error_message": "The video could not be processed."
}error_message is deprecated. If present, it repeats the curated error.detail and does not expose stored internal failure text.
Problem Types
The error registry lists every problem type. Common types include bad-request, validation-error, unauthorized, forbidden, resource-not-found, conflict, idempotency-in-flight, unprocessable-entity, idempotency-payload-mismatch, rate-limit-exceeded, internal-error, and service-unavailable.
Branch on type, not on detail or on the HTTP status alone. Do not automatically retry a 4xx response other than 429.