Errors

Non-2xx responses carry machine-readable error codes. This page maps those responses to the caller behaviors you should implement in a production integration.

3 min read

Rely on the error envelope

Non-2xx responses use a stable error envelope with type, code, and message fields.

Validation failures return 400, authentication failures return 401, missing resources return 404, and duplicate/conflict cases return 409.

Every non-2xx response includes a machine-readable code and a human-readable message. Build your retry and alerting behavior around the code, not the prose.

Map status codes to caller behavior

400 means the request shape or values are invalid.
401 means the key is missing or invalid.
404 means the target job or resource does not exist in the authenticated workspace.
409 means the request conflicts with existing state and should be corrected before retrying.

Validation error

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_body",
    "message": "Request body is invalid."
  }
}

Need help shipping an integration?

Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.

Contact Mailrith

Related guides

3 min read

Authentication

Use workspace-scoped Bearer keys and understand how protected requests are authorized.

3 min read

Idempotency

Retry async job creation safely with the `Idempotency-Key` header.

4 min read

Import and Export Jobs

Create async subscriber import and export jobs and poll them to completion.

Pagination

Idempotency