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.
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.
- Check the HTTP status code first to identify the broad failure class.
- Read
error.typeanderror.codefrom the response body. - Log the status, code, request path, workspace or integration name, and job ID if one exists.
- Show
error.messageto an operator when a person needs to correct input or credentials. - Retry only when the HTTP status and Mailrith error code indicate a temporary condition.
- Use Idempotency before retrying async job creation.
-
typegroups the error into a broad category such as authentication, validation, conflict, or not found. -
codeidentifies the exact problem so your integration can choose the correct branch. -
messageexplains the problem in plain language for logs, dashboards, and people troubleshooting the request. - A successful response uses
data; an unsuccessful response useserror. Handle those response paths separately.
{
"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.
-
400means the request shape or values are invalid. Fix the request before retrying. -
401means the key is missing, malformed, revoked, or unknown. Replace the credential before retrying. -
404means the target resource does not exist in the authenticated workspace. Check that the ID and workspace key are correct. -
409means the request conflicts with current state. Correct the state or payload before retrying. -
429means the caller is sending requests too quickly. Back off before trying again. -
500and 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.
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 stateNeed Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.