Skip to main content
Errors are indicated by standard HTTP status codes. Branch on the status code first, then read the JSON body for detail. The expected status codes for each endpoint are listed with that endpoint in the API Reference.

​
Error response body

Error responses carry a JSON body. Parse it rather than the status text. You should also log the X-Trace-ID response header, as it will help our team debug if you need to raise a support ticket.
Example error response
Don’t match on message strings. They are written for humans and are not part of the API contract. Use the status code, and code where it is present.
Failures that occur before a request reaches the API, in DeepL’s edge infrastructure, use a nested shape instead, with the message under an error object:
Example infrastructure error response
Handle both shapes in your parser. Reading body.message ?? body.error?.message covers every error the API can return, and keeps your client from crashing on a gateway error during an incident.

​
Which errors to retry

Details on the errors you are most likely to hit:
  • HTTP 429: too many requests. You may receive this when sending many API requests in a short period of time. Resend the request after a delay, using retries with exponential backoff. This is implemented in all of the official, DeepL-supported client libraries.
  • HTTP 456: quota exceeded. If you’re a Free API user, you’ll receive this error when the monthly 500,000 character limit of your subscription has been reached. You can consider upgrading your subscription if you need more character volume. If you’re a Pro API user, you’ll receive this error when your Cost Control limit has been reached, and you can increase or remove your Cost Control limit if you need to continue translating. You can also use the usage endpoint to find out your currently used and available quota.
  • HTTP 500: internal server error. You’ll receive this if there are temporary errors in DeepL services. Resend the request after a delay, using retries with exponential backoff. Check the API Status Page for current service availability and incident information.

​
Throttling your client

The service dynamically adjusts to the load on the system, so there is no fixed request-per-second figure to code against. Design your client to find the limit rather than to assume one:
  • Retry 429 and 5xx responses with exponential backoff and jitter. Honor the Retry-After header when a response includes one, in preference to your own backoff interval
  • Cap the number of requests you have in flight at once, and lower that cap while you are receiving 429 responses
  • Batch multiple strings into a single translate request instead of sending one request per string, staying inside the request size limit
  • Treat 456 as a stop condition, not a retry condition, and poll the usage endpoint to see how close an account is to its quota before you get there
As the service adapts to your traffic, you will be able to send increasingly more requests within a given amount of time without encountering errors.