Errors and retries

Handle API errors based on the status code, error body, and whether it is safe to try again.

Management API validation errors

Management API validation errors usually look like this:

{
  "message": "Validation failed",
  "errors": [
    {
      "field": "name",
      "description": "already exists"
    }
  ]
}

Common statuses:

Status	Meaning	Retry?
`401`	Missing or invalid authentication.	No. Fix the token.
`403`	Authenticated, but not allowed.	No. Fix permissions, resource ownership, account status, billing profile, or plan state.
`404`	Resource not found or not visible to the current user.	No, unless the resource may be created later.
`422`	Validation failed.	No. Fix request fields.
`500`	Server error.	Maybe. Retry with backoff if the operation is safe to repeat.

Billing profile required

For production Management API provisioning, 403 Forbidden can mean the customer has no billing profile yet. In that case, log into the Qboxmail panel and complete the first order before retrying paid provisioning. This does not apply to sandbox, and active Hosting trial or Free Hosting customers can manage Hosting resources without a billing profile.

Send API errors

Send API errors use a stable JSON format:

{
  "error_code": 400,
  "message": "Request body must include a non-empty `messages` array.",
  "error": "missing_send_payload",
  "request_id": "f43eb659-beb4-4f8a-a737-2d403998f4cf"
}

Always log request_id. It lets you correlate client logs, API logs, TraceMail events, and support investigations.

If a Send API call fails because of authentication, permissions, quota, or domain settings, check the Delivery setup first: account, sending domain, token, IP allow-list, and account status.

Send API status guide

Status	Examples	Retry?
`400`	Invalid JSON, missing payload, invalid message fields, missing bulk substitutions.	No. Fix payload.
`401`	Missing or invalid bearer token.	No. Create or fix the Send API token for the Delivery account.
`403`	IP not allowed, account disabled, plan not started or expired.	No. Fix Delivery account, token, domain, or IP configuration.
`413`	Payload larger than allowed.	No. Split the request or reduce attachments.
`429`	Request rate limit or quota exceeded.	Yes, only after `Retry-After` or with backoff when appropriate.
`502`	Queue or downstream delivery service unavailable.	Yes, with exponential backoff.
`503`	Temporary reservation conflict or unavailable service.	Yes, with exponential backoff.
`504`	Downstream timeout.	Maybe. Retry carefully and reconcile duplicates.

Retry strategy

Recommended client behavior:

Do not retry 400, 401, 403, 404, or 422 without changing the request.
For 429, respect the Retry-After header when present.
For 502, 503, and 504, retry with exponential backoff and jitter.
Cap retries. Do not retry forever.
Store your own correlation data in application logs so you can reconcile ambiguous outcomes.

Be careful after network failures

If the client loses the connection before receiving a response, the message may or may not have been queued. Avoid blind retries for large or important sends unless your application can tolerate duplicates or reconcile them later.

Good logging fields

For Management API requests, log:

endpoint and method;
authenticated integration/user;
resource code or ID;
response status;
validation errors.

For Send API requests, log:

request_id;
each returned message_id;
recipient count;
suppression summary;
response status and error code when present.