Errors & Troubleshooting
Understand the error codes returned by the Editly API so you can handle edge cases gracefully in your application.
HTTP Status Codes
The API uses standard HTTP response codes to indicate the success or failure of each request.
| Code | Status | Description |
|---|---|---|
| 200 / 202 | Success | The request was successful or the job was successfully enqueued. |
| 400 | Bad Request | The request was unacceptable — missing or invalid parameters. |
| 401 | Unauthorized | No valid API key was provided in the Authorization header. |
| 402 | Payment Required | Your account has insufficient credits to perform the generation. |
| 404 | Not Found | The requested resource (e.g., job ID) does not exist or belongs to another user. |
| 429 | Too Many Requests | You have hit the API rate limit. Please retry after a short delay. |
| 500 | Server Error | Something went wrong on Editly's end. Retries are handled automatically. |
Async Job Errors
When an AI generation job fails asynchronously (after you've received a 202), the job status will transition to FAILED. Credits are automatically refunded for all failed jobs.
RATE_LIMITThe upstream AI provider is currently overwhelmed. Editly handles retries automatically via Inngest, but if all retries are exhausted the job will fail. Your credits are automatically refunded.
PROVIDER_ERRORThe underlying AI model failed to generate the asset due to content policies, prompt complexity, or internal provider issues. Credits are automatically refunded.
AUTHENTICATION_ERRORA misconfiguration occurred with Editly's provider keys. This is monitored actively and should be resolved shortly.
VALIDATION_FAILEDYour API payload failed schema validation. The error response will contain a details array specifying exactly which fields were invalid.
Best Practices
Implement exponential backoff
When polling for job status, start with a 2-second interval and double it on each retry to avoid hitting rate limits.
Handle FAILED status explicitly
Always check for FAILED status in addition to COMPLETED. Credits are refunded but you should surface the error to your users.
Store job IDs
Persist job IDs immediately after receiving the 202 response. If your connection drops, you can always resume polling later.
Validate inputs client-side
Pre-validate modelId, prompt length, type, and aspectRatio before sending requests to avoid 400 errors.