# Errors > Non-2xx responses include stable error codes and plain-language messages. This guide explains how to log errors, avoid matching on message text, map status codes to user or system actions, and retry only when the same request may succeed later. - Human page: https://mailrith.com/developers/errors - Markdown page: https://mailrith.com/developers/errors.md - Category: API Concepts - Reading time: 6 min read - Last updated: 2026-07-13 - Related keywords: Errors, Errors developer docs, API Concepts, API Concepts developer docs, Mailrith developer docs, Mailrith public API, Rely on the Error Envelope, Map Status Codes to Caller Behavior, Decide When to Retry, Authentication, Idempotency, Import and Export Jobs ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## What this guide covers Read Mailrith error envelopes, map status codes to behavior, and decide when retrying a request is safe. ## Rely on the Error Envelope Every non-2xx Mailrith response uses the same error envelope. In the API response, find the top-level `error` object, then read `type`, `code`, and `message`. `message` is written for people and can be shown in logs or support screens. `code` is written for software and should control your retry, alerting, and user-correction behavior. Do not build logic by matching the full message text. Messages may change to become clearer, but the code is the stable value your integration can depend on. 1. Check the HTTP status code first to identify the broad failure class. 2. Read `error.type` and `error.code` from the response body. 3. Log the status, code, request path, workspace or integration name, and job ID if one exists. 4. Show `error.message` to an operator when a person needs to correct input or credentials. 5. Retry only when the HTTP status and Mailrith error code indicate a temporary condition. 6. Use [Idempotency](https://mailrith.com/developers/idempotency.md) before retrying async job creation. - `type` groups the error into a broad category such as authentication, validation, conflict, or not found. - `code` identifies the exact problem so your integration can choose the correct branch. - `message` explains the problem in plain language for logs, dashboards, and people troubleshooting the request. - A successful response uses `data`; an unsuccessful response uses `error`. Handle those response paths separately. **Validation Error Response** ```json { "error": { "type": "invalid_request", "code": "invalid_body", "message": "Request body is invalid." } } ``` ## Map Status Codes to Caller Behavior HTTP status codes tell your integration the broad problem class. Mailrith's error code tells your integration what action to take next. Do not handle every failed production request the same way. Some failures need corrected input, some need a new credential, some need a missing resource to be recreated, and some can be retried later. Always log the status code, Mailrith error code, request path, and integration job name together. These fields give the person debugging the issue enough context without exposing the full API key or private subscriber data. - `400` means the request shape or values are invalid. Fix the request before retrying. - `401` means the key is missing, malformed, revoked, or unknown. Replace the credential before retrying. - `404` means the target resource does not exist in the authenticated workspace. Check that the ID and workspace key are correct. - `409` means the request conflicts with current state. Correct the state or payload before retrying. - `429` means the caller is sending requests too quickly. Back off before trying again. - `500` and other server-side errors can usually be retried with backoff, but keep the original error information for troubleshooting. ## Decide When to Retry Retries help only when the same request may succeed later. Retry a timeout, a temporary network failure, or a server-side problem. Do not retry a malformed request body or invalid API key until you fix the request body or replace the credential. For background jobs and syncs, use exponential backoff so one failure does not create hundreds of repeated requests. For user-triggered actions, show a clear error and let the user try again after the problem is fixed. When a create operation is safe to retry only once, follow the idempotency guidance in these docs. Idempotency lets Mailrith recognize that a retry is the same logical request, not new duplicate work. **Simple Retry Decision Table** ```text Retry later: - Network timeout - 429 rate limit response - 500-level temporary server error Do not retry until fixed: - 400 invalid request body - 401 invalid API key - 404 wrong resource id or wrong workspace key - 409 conflicting state ``` ## Related Guides - [Authentication](https://mailrith.com/developers/authentication.md): Every protected `v1` request is authorized through a workspace-scoped API key. This page covers the required header shape, workspace scoping behavior, and authentication failure handling. - [Idempotency](https://mailrith.com/developers/idempotency.md): Import and export job creation endpoints accept idempotency keys so network retries do not queue duplicate work. This guide explains when to use a key, how to choose one, and how to store the key with your own job record. - [Import and Export Jobs](https://mailrith.com/developers/jobs.md): Imports and exports are asynchronous in `v1`. This guide explains when to queue a job, how import mappings and export filters work at a high level, how to use idempotency, and how to monitor final job status without confusing queued work with completed work.