The OrbConvert API uses conventional HTTP status codes. Every error response includes a JSON body with a machine-readable code and a human-readable message.
| Code | Name | Description | How to fix |
|---|---|---|---|
| 400 | Bad Request | The request was malformed — invalid JSON, missing required field, unsupported format, or invalid option value. | Check the request body against the API reference. Ensure fileId is valid and toFormat is supported for the file's category. |
| 401 | Unauthorized | Authentication is missing or invalid. The x-api-key header or Authorization: Bearer token is absent, expired, or revoked. | Verify your API key in Settings → API Keys. For JWT, refresh the token via POST /api/auth/refresh. |
| 403 | Forbidden | Your account is banned, the feature flag is disabled, or you lack permission for this operation. | Contact support if you believe this is an error. Check that the feature is available on your plan. |
| 404 | Not Found | The conversion ID or file ID does not exist, or you do not own the resource. | Verify the ID from the conversion response. Ensure you're using the same API key that created the conversion. |
| 413 | Payload Too Large | The uploaded file exceeds your plan's maximum file size limit (Guest: 25 MB, Free: 100 MB, Pro: 2 GB, Business: 5 GB). | Reduce the file size before uploading, or upgrade to a plan with higher limits. |
| 429 | Too Many Requests | A rate limit was exceeded — an endpoint's own limit (see the Rate Limits page for your plan's numbers), the shared 100-per-15-minutes ceiling that applies to requests with no account, or your daily conversion quota. | Wait for the window to reset. Read Retry-After (seconds) or RateLimit-Reset on the response, then throttle to the limit for the endpoint you are calling. |
| 500 | Internal Server Error | The conversion engine encountered an unexpected error processing your file. | Retry the request. If the error persists, the file may be corrupted or in an edge-case format. Contact support with the conversion ID. |
All errors return a JSON object with an error field containing code, message, and optionally field for validation errors.
{
"error": {
"code": "INVALID_OPTION_VALUE",
"message": "Option 'quality' must be between 1 and 100",
"field": "options.quality"
}
}Rate-limited responses carry rate limit headers so you can throttle proactively. The per-endpoint limiters send both families below on every response; the shared ceilings send the standard family and add the legacy one when they refuse:
RateLimit-Limit: 120 RateLimit-Remaining: 87 RateLimit-Reset: 43 # The legacy spellings of the same three values, sent alongside. # Mind the Reset convention: absolute epoch second here, seconds-from-now above. X-RateLimit-Limit: 120 X-RateLimit-Remaining: 87 X-RateLimit-Reset: 1697000000
The conversion API validates options against the target format's category. Three error codes relate specifically to options:
UNKNOWN_OPTION
The option key is not in the server's OPTION_SPECS at all.
OPTION_NOT_APPLICABLE
The option exists but does not apply to the target format's category (e.g., sending 'bitrate' for a PDF).
INVALID_OPTION_VALUE
The option key is valid for the category but the value is out of range or wrong type.
Was this page helpful?