> For the complete documentation index, see [llms.txt](https://docs.mdintegrations.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mdintegrations.com/partner/troubleshooting/technical-concepts/error-codes-and-handling.md). # Error Codes & Handling When a request to the MDI API fails, you get back a JSON body describing what went wrong, alongside an HTTP status code that tells you, at a glance, which category of failure you're dealing with. Branch on the status code first — it's the fastest way to decide whether to retry, refresh a token, or surface an error to the end user, before you even look at the body's details. ## Error response shape Error bodies are JSON and generally include: ```json { "error": "Missing required field: date_of_birth", "message": "We couldn't process your request. Please check the information you provided.", "code": "VALIDATION_ERROR" } ``` * **`error`** — a developer-facing description of what went wrong. Useful for logging and debugging. * **`message`** — an end-user-facing message, safe to surface directly in your UI if you don't have a more specific one of your own. * **`code`** — a machine-readable identifier for the specific failure, useful for programmatic branching beyond the HTTP status alone. ## HTTP status codes | Status | Meaning | What to do | | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `401` | Authentication failed — missing, invalid, or expired token. | Refresh your token (see Token Expiration & Refresh) and retry once. | | `403` | Authenticated, but not authorized for this action — a policy or permission denial, such as trying to access another partner's resource. | Don't retry with the same credential. Check that the resource actually belongs to your partner and environment. | | `404` | The resource ID doesn't exist, or doesn't belong to your partner/environment. | Verify the ID. A common cause is using a Sandbox-created ID against a Live credential, or vice versa. | | `422` | Validation error — a required field is missing or malformed. | Inspect the `error` and `message` fields to identify which field failed, then correct the request. | | `5xx` | An issue on MDI's side. | Safe to retry with backoff. | {% hint style="warning" %} The `404`/environment mismatch is one of the most common integration bugs partners run into. If an ID you're confident exists returns `404`, check which credential — Sandbox or Live — you authenticated with before assuming the resource is actually missing. See Sandbox vs. Live Environments. {% endhint %} ## Common token-request errors Requests to the token endpoint (`/v1/partner/auth/token`) can fail before you ever have a Bearer token to work with, and two failures in particular are the ones you're most likely to run into: * **`422`** — your credentials weren't sent in a recognized format. Provide `client_id` and `client_secret` either as JSON body fields or as an `Authorization: Basic base64(client_id:client_secret)` header — not a mix of both. Check that your request consistently uses one format throughout. * **`401`** — client authentication failed. Your `client_id`/`client_secret` pair wasn't recognized; re-check them against what's shown in the Partner control panel, and confirm the credential hasn't since been rotated or revoked. ## Building a general-purpose handler Because every endpoint follows this same envelope and status code convention, you can write one error-handling function and reuse it everywhere, rather than special-casing each integration point: {% stepper %} {% step %} Check the HTTP status first. {% endstep %} {% step %} On `401`, refresh the token and retry once. {% endstep %} {% step %} On `403` or `404`, don't retry — surface the issue or log it for investigation. {% endstep %} {% step %} On `422`, parse `error`/`message` to identify the bad field and stop retrying until the request is corrected. {% endstep %} {% step %} On `5xx`, retry with exponential backoff, up to a reasonable limit. {% endstep %} {% endstepper %} ## Finding specific error codes The `code` field's exact catalog of values — and what triggers each one — varies by endpoint and evolves over time, so it isn't reproduced in full here. This page covers the shape of the error envelope and the status codes you'll branch on; for the current, authoritative list of `code` values per endpoint, see the Full API Reference. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.mdintegrations.com/partner/troubleshooting/technical-concepts/error-codes-and-handling.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.