DeepL · shirgoldbird · Sep 2, 2026
diff --git a/.mintignore b/.mintignore
@@ -1,3 +1 @@
 reviews/*
-api-reference/openapi.json
-api-reference/voice/voice.asyncapi.json
diff --git a/docs.json b/docs.json
@@ -2,6 +2,7 @@
   "$schema": "https://mintlify.com/docs.json",
   "theme": "mint",
   "name": "DeepL Documentation",
+  "description": "Developer documentation for the DeepL API: translate text and documents, transcribe and translate speech in real time, improve text, and customize output with glossaries, style rules, and translation memories.",
   "colors": {
     "primary": "#0f2b46",
     "light": "#ffffff",
@@ -101,6 +102,13 @@
                 "drilldown": false
               }
             ]
+          },
+          {
+            "group": "Support",
+            "pages": [
+              "docs/resources/contact",
+              "docs/resources/privacy"
+            ]
           }
         ]
       },
@@ -418,6 +426,10 @@
           {
             "label": "DeepL Status",
             "href": "https://status.deepl.com"
+          },
+          {
+            "label": "Contact",
+            "href": "/docs/resources/contact"
           }
         ]
       }
@@ -430,6 +442,8 @@
     }
   },
   "api": {
+    "openapi": "api-reference/openapi.yaml",
+    "asyncapi": "api-reference/voice/voice.asyncapi.yaml",
     "examples": {
       "languages": [
         "curl"
@@ -442,7 +456,9 @@
   },
   "errors": {
     "404": {
-      "redirect": false
+      "redirect": false,
+      "title": "Page not found",
+      "description": "This page does not exist. Humans: check out the [Quickstart](/docs/getting-started/quickstart) or the [API reference](/api-reference/translate/request-translation). Machines: try [/llms.txt](/llms.txt), [the docs MCP server](https://developers.deepl.com/mcp), or OpenAPI specs for [Text](/api-reference/openapi.yaml) and [Voice](/api-reference/voice/voice.asyncapi.yaml)."
     }
   },
   "redirects": [
@@ -749,6 +765,50 @@
     {
       "source": "/docs/learning-how-tos/cookbook/context-parameter-examples",
       "destination": "/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter"
+    },
+    {
+      "source": "/about",
+      "destination": "/docs/getting-started/about"
+    },
+    {
+      "source": "/contact",
+      "destination": "/docs/resources/contact-and-support"
+    },
+    {
+      "source": "/contact-us",
+      "destination": "/docs/resources/contact-and-support"
+    },
+    {
+      "source": "/support",
+      "destination": "/docs/resources/contact-and-support"
+    },
+    {
+      "source": "/privacy",
+      "destination": "/docs/resources/privacy-and-data-security"
+    },
+    {
+      "source": "/openapi.yaml",
+      "destination": "/api-reference/openapi.yaml"
+    },
+    {
+      "source": "/openapi.json",
+      "destination": "/api-reference/openapi.json"
+    },
+    {
+      "source": "/api/openapi.yaml",
+      "destination": "/api-reference/openapi.yaml"
+    },
+    {
+      "source": "/api/openapi.json",
+      "destination": "/api-reference/openapi.json"
+    },
+    {
+      "source": "/asyncapi.yaml",
+      "destination": "/api-reference/voice/voice.asyncapi.yaml"
+    },
+    {
+      "source": "/asyncapi.json",
+      "destination": "/api-reference/voice/voice.asyncapi.json"
     }
   ],
   "integrations": {
@@ -788,6 +848,38 @@
         "src": "/user-data.js",
         "defer": true
       }
+    },
+    {
+      "tag": "script",
+      "attrs": {
+        "type": "application/ld+json"
+      },
+      "children": "{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://www.deepl.com/#organization\",\"name\":\"DeepL\",\"legalName\":\"DeepL SE\",\"alternateName\":\"DeepL SE\",\"description\":\"DeepL SE is a Language AI company. Its developer products include the DeepL API for text, document, and real-time voice translation, and the DeepL Write API for text improvement.\",\"url\":\"https://www.deepl.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://static.deepl.com/img/logo/deepl-logo-blue.svg\"},\"email\":\"info@deepl.com\",\"faxNumber\":\"+49 221 95018653\",\"vatID\":\"DE349242045\",\"foundingDate\":\"2017\",\"address\":{\"@type\":\"PostalAddress\",\"streetAddress\":\"Maarweg 165\",\"postalCode\":\"50825\",\"addressLocality\":\"Cologne\",\"addressCountry\":\"DE\"},\"contactPoint\":[{\"@type\":\"ContactPoint\",\"contactType\":\"technical support\",\"url\":\"https://developers.deepl.com/docs/resources/contact-and-support\",\"areaServed\":\"Worldwide\",\"availableLanguage\":[\"en\"]},{\"@type\":\"ContactPoint\",\"contactType\":\"customer support\",\"url\":\"https://support.deepl.com/hc/en-us/requests/new\",\"areaServed\":\"Worldwide\"},{\"@type\":\"ContactPoint\",\"contactType\":\"sales\",\"url\":\"https://www.deepl.com/en/contact-us\",\"areaServed\":\"Worldwide\"},{\"@type\":\"ContactPoint\",\"contactType\":\"security\",\"email\":\"security@deepl.com\",\"areaServed\":\"Worldwide\",\"availableLanguage\":[\"en\"]}],\"sameAs\":[\"https://github.com/DeepL\",\"https://www.linkedin.com/company/deepl\",\"https://x.com/DeepLcom\",\"https://www.youtube.com/@DeepLcom\",\"https://en.wikipedia.org/wiki/DeepL_Translator\"]},{\"@type\":[\"SoftwareApplication\",\"WebAPI\"],\"@id\":\"https://developers.deepl.com/#deepl-api\",\"name\":\"DeepL API\",\"description\":\"REST and WebSocket APIs for translating text and documents, transcribing and translating speech in real time, improving text, and customizing output with glossaries, style rules, and translation memories.\",\"url\":\"https://developers.deepl.com\",\"applicationCategory\":\"DeveloperApplication\",\"operatingSystem\":\"Any\",\"provider\":{\"@id\":\"https://www.deepl.com/#organization\"},\"documentation\":\"https://developers.deepl.com/docs/getting-started/quickstart\",\"termsOfService\":\"https://www.deepl.com/pro-license\",\"privacyPolicy\":\"https://www.deepl.com/en/privacy\",\"offers\":[{\"@type\":\"Offer\",\"name\":\"DeepL API Free\",\"url\":\"https://www.deepl.com/en/pro#api\",\"price\":\"0\",\"priceCurrency\":\"EUR\",\"category\":\"free\"},{\"@type\":\"Offer\",\"name\":\"DeepL API Pro\",\"url\":\"https://www.deepl.com/en/pro#api\",\"category\":\"subscription\"}]}]}"
+    }
+  ],
+  "markdown": {
+    "instructions": [
+      "Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints.",
+      "Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication).",
+      "Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key <api-key>`. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart.",
+      "Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid."
+    ]
+  },
+  "seo": {
+    "indexing": "navigable",
+    "organization": {
+      "id": "https://www.deepl.com/",
+      "name": "DeepL",
+      "legalName": "DeepL SE",
+      "url": "https://www.deepl.com",
+      "logo": "https://static.deepl.com/img/logo/deepl-logo-blue.svg",
+      "sameAs": [
+        "https://github.com/DeepL",
+        "https://www.linkedin.com/company/deepl",
+        "https://x.com/DeepLcom",
+        "https://www.instagram.com/deeplhq/",
+        "https://www.youtube.com/@DeepLcom"
+      ]
     }
-  ]
+  }
 }
diff --git a/docs/best-practices/error-handling.mdx b/docs/best-practices/error-handling.mdx
@@ -1,17 +1,70 @@
 ---
 title: "Error handling"
+description: "Parse DeepL API error responses, decide which status codes to retry, and throttle your client so it stays inside the API's limits."
 mode: "wide"
 public: true
 ---
 
-Errors are indicated by [standard HTTP status codes](https://developer.mozilla.org/docs/Web/HTTP/Status). It is important to make sure that your application handles errors in an appropriate way. To that end, please consult the list of expected status code results that are provided with each endpoint's documentation in the API Reference.
+Errors are indicated by [standard HTTP status codes](https://developer.mozilla.org/docs/Web/HTTP/Status). 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](/api-reference/translate/request-translation).
 
-* **HTTP 429: too many requests.** This is an error that you might receive when sending many API requests in a short period of time. Your application should be configured to resend the requests after some delay. Specifically, we recommend implementing retries with exponential backoff. This is implemented in all of the official, DeepL-supported [client libraries](/docs/getting-started/client-libraries).
+## Error response body
 
-* **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](https://www.deepl.com/pro) if you need more character volume. **If you're a Pro API user**, you'll receive this error when your [Cost Control](/docs/best-practices/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](/api-reference/usage-and-quota/check-usage-and-limits) to find out your currently used and available quota.
+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.
 
-* **HTTP 500: internal server error** This is an error you'll receive if there are temporary errors in DeepL Services. Your application should be configured to resend the requests after some delay. Specifically, we recommend implementing retries with exponential backoff. This is implemented in all of the official, DeepL-supported [client libraries](/docs/getting-started/client-libraries). You can check the [API Status Page](https://status.deepl.com/?tab=api) for current service availability and incident information.
+```json Example error response
+{
+  "message": "Value for 'target_lang' not supported."
+}
+```
 
-The service dynamically adjusts to the load on the system. Please wait to stop receiving errors to send more requests again. As the service adapts, you will be able to send increasingly more requests within a given amount of time without encountering errors.
+| **Field** | **Description** |
+| --- | --- |
+| `message` | Human-readable description of the error. Present on error responses |
+| `code` | Machine-readable identifier for the error, where available. Branch on this rather than on `message`, which can change wording |
 
-Additional information may be provided by a JSON response that contains more details about the error. In this case, this additional information will be contained in the message key.
+<Warning>
+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.
+</Warning>
+
+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:
+
+```json Example infrastructure error response
+{
+  "error": {
+    "message": "Bad Gateway."
+  }
+}
+```
+
+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
+
+| **Status** | **Meaning** | **Retry?** |
+| --- | --- | --- |
+| `400` | The request itself is invalid | No. Fix the request |
+| `403` | Authorization failed, or the API key lacks the [permission scope](/docs/admin/permission-scopes) for this endpoint | No. Check the key and its scopes |
+| `404` | The resource does not exist, or a document has already been downloaded | No |
+| `413` | The request exceeds the [request size limit](/docs/resources/usage-limits) | No. Split the payload into smaller requests |
+| `429`, `529` | Too many requests in a short period | Yes, with exponential backoff |
+| `456` | Quota exhausted for the billing period or for a [Cost Control](/docs/best-practices/cost-control) limit | No. Retrying will not succeed until the quota is raised or the period resets |
+| `500`, `503`, `504` | Temporary error in DeepL services | Yes, with exponential backoff |
+
+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](/docs/getting-started/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](https://www.deepl.com/pro) if you need more character volume. **If you're a Pro API user**, you'll receive this error when your [Cost Control](/docs/best-practices/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](/api-reference/usage-and-quota/check-usage-and-limits) 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](https://status.deepl.com/?tab=api) 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](/api-reference/translate/request-translation) instead of sending one request per string, staying inside the [request size limit](/docs/resources/usage-limits)
+* Treat `456` as a stop condition, not a retry condition, and poll the [usage endpoint](/api-reference/usage-and-quota/check-usage-and-limits) 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.
diff --git a/docs/getting-started/about.mdx b/docs/getting-started/about.mdx
@@ -1,5 +1,6 @@
 ---
 title: "About"
+description: "Understand what the DeepL API does."
 public: false
 mode: "wide"
 ---
@@ -26,10 +27,4 @@ In addition, many leading computer-assisted translation (CAT) tool providers hav
 - **Maximum data security**: With DeepL API paid plans, texts aren’t saved on persistent storage and aren’t used to train our models. And DeepL adheres strictly to EU data protection laws and ISO 27001. [Learn more about data security at DeepL](https://www.deepl.com/pro-data-security/).
 - **Customization with glossaries**: [Specify your own translations for words and phrases](/docs/customize/managing-glossaries), and customize your translations consistently and at scale.
 
-To access the DeepL API, [sign up for a plan](https://www.deepl.com/en/pro#api).
-
----
-
-**Intended Purpose of the DeepL API**
-
-DeepL API is intended to translate or otherwise process general documents or other content provided by the Customer in accordance with the documentation. DeepL API is not intended for any high-risk applications as defined in [Article 6 of the EU AI Act](https://artificialintelligenceact.eu/article/6/) (including any applicable delegated acts adopted by the European Commission on the basis of this provision).
+To access the DeepL API, [sign up for a plan](https://www.deepl.com/en/pro#api).
diff --git a/docs/resources/contact.mdx b/docs/resources/contact.mdx
@@ -0,0 +1,33 @@
+---
+title: "Contact"
+description: "Find the right DeepL channel to get help with our API."
+---
+
+Support for the DeepL API is split across a few channels.
+
+## Where to send your request
+
+| **What you need** | **Where to go** |
+| --- | --- |
+| Discussion and knowledge sharing about the API | [DeepL Developer Community on Discord](https://discord.gg/deepl) |
+| Account, subscription, billing, or plan changes | [Submit a support request](https://support.deepl.com/hc/en-us/requests/new) |
+| Pricing, volume plans, or enterprise agreements | [Contact DeepL sales](https://www.deepl.com/en/contact-us) |
+| A security vulnerability | Email [security@deepl.com](mailto:security@deepl.com). A PGP public key is published in [`SECURITY.md`](https://github.com/DeepL/api-docs/blob/main/SECURITY.md) |
+| Issues with the documentation | [Open an issue on `DeepL/api-docs`](https://github.com/DeepL/api-docs/issues) |
+| DeepL API availability and status | [DeepL API status page](https://status.deepl.com/?tab=api) |
+| General answers | [DeepL Help Center](https://support.deepl.com/hc/en-us) |
+
+## Before you open a support request
+
+Include the following to help us get you the fastest possible answer:
+
+- The `X-Trace-ID` response header from a failing request. DeepL API responses include this header, and it identifies that exact request in DeepL's logs
+- The HTTP status code and the JSON `message` from the response body
+- The endpoint you called
+- The email address your subscription is linked to
+
+Never include an API key or sensitive content in your message. If a key has been exposed, [deactivate it immediately](/docs/admin/managing-api-keys).
+
+## Company details
+
+DeepL API products are provided by DeepL SE. Full publisher information is available on the [DeepL publisher page](https://www.deepl.com/publisher).