Error Codes
This page documents all HTTP status codes and error messages returned by the Enconvert API.
HTTP Status Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Conversion completed successfully (sync mode). |
| 202 | Accepted | Batch or async job has been accepted for processing. |
| 400 | Bad Request | Invalid parameters, missing required fields, or malformed request body. |
| 401 | Unauthorized | Missing, invalid, or expired API key or JWT token. |
| 402 | Payment Required | Monthly conversion limit has been exceeded. |
| 403 | Forbidden | Private key used from a browser, domain not authorized, or endpoint not allowed for this key. |
| 404 | Not Found | The requested resource does not exist. |
| 413 | Payload Too Large | Uploaded file exceeds the size limit for your subscription tier. |
| 429 | Too Many Requests | Rate limit exceeded. Slow down and retry after a delay. |
| 500 | Internal Server Error | An unexpected error occurred on the server. |
| 503 | Service Unavailable | A backend service is temporarily unavailable. Try again shortly. |
Error Response Format
All error responses follow a consistent JSON structure with a detail field describing the issue:
{
"detail": "Domain app.example.com not authorized for this API key"
}
Common Error Messages
The table below lists common error messages, their associated HTTP status codes, and the typical cause.
| Message | Code | Cause |
|---|---|---|
| Invalid API Key format | 401 | The API key does not match the expected sk_ or pk_ prefix format. |
| API Key revoked | 401 | The API key has been revoked from the dashboard and is no longer valid. |
| Token has expired | 401 | The JWT access token has expired. Request a new token or use the refresh endpoint. |
| Refresh token has expired | 401 | The refresh token has expired. Re-authenticate using your API key. |
| Refresh token not found | 401 | The refresh token provided does not exist or has already been consumed. |
| Invalid token | 401 | The JWT token is malformed, tampered with, or otherwise invalid. |
| Private API keys cannot be used from browsers | 403 | A private key (sk_) was used in a request originating from a browser. Use a public key with JWT instead. |
| Domain not authorized | 403 | The request origin does not match any domain in the API key's whitelist. |
| Public API keys can only be used to generate JWT tokens | 403 | A public key (pk_) was used to call a conversion endpoint directly. Public keys must first be exchanged for a JWT via /v1/auth/token. |
| Endpoint not allowed by this API key | 403 | The API key or widget token is restricted and does not have access to the requested endpoint. |
| Monthly conversion limit reached | 402 | The free tier's 20 monthly conversions have been exhausted. Upgrade your plan or wait until the next month. |
| File too large | 413 | The uploaded file exceeds the maximum size allowed for your subscription tier. |
| Service temporarily unavailable | 503 | A backend dependency is down or undergoing maintenance. Retry after a short delay. |