Error Handling

Use error categories to decide what to inspect and what to do next.

Error envelope

Every JSON operation (all of Orders v1, Rates, label purchase, and cancellation) returns the same failure shape:

{
  "success": false,
  "data": null,
  "errors": [
    { "code": "...", "message": "...", "metaData": null }
  ]
}

POST /api/v2/orders is the one exception — its data contains order, shipmentRates, status, and operation-specific errors. Download a Label answers with a flat error object instead of this envelope on every failure but 401 — inspect its HTTP status and Content-Type before parsing. See API Conventions for the full shape reference.

Statuses any operation can return

These are decided before an operation's own logic runs, so every operation can answer with them. Each operation documents its own statuses on top of these in the API Reference.

Status	Meaning
400	The request could not be read as sent — for example an X-SubAccount-Id header that is not a GUID.
401	The request carries no usable credential: missing, malformed, expired, or revoked.
403	Authenticated, but not with an Open API integration token. Sent without a body — there is nothing to parse.
404	The sub-account given in X-SubAccount-Id does not exist or belongs to another account.
409	The sub-account given in X-SubAccount-Id is not active.
500	The request could not be completed because of an unexpected server-side failure.

The two anonymous token operations (refresh and revoke) never look a sub-account up, so they answer 400 for a malformed header but never 404 or 409 for one.

503 is not in this table: it is not raised by the shared pipeline. It comes only from operations that call a carrier — rates, label purchase and download (Label Errors), and Create an Order with Rates. It means the carrier, not Mailhub, is unavailable: nothing in the request is wrong, so correcting it changes nothing and only a later retry can succeed.

Recovery model

Inspect, correct, retry cautiously, or stop.

• Inspect the operation, environment, identifiers, and sanitized failure summary.
• Correct missing or invalid business data before resubmitting.
• Retry only when the documented operation behavior makes it appropriate.
• Stop repeated attempts after an ambiguous state-changing result.
• Record sanitized context for your application's operational process; the API does not define a recovery sequence for an ambiguous state-changing result.

Categories

• Authentication Errors
• Validation Errors
• Order State Errors
• Rate Errors
• Label Errors — purchase, binary download, and cancellation
• Create an Order with Rates documents its own per-shipment error array; it is not a separate error category here

The public API does not currently declare a 429 rate-limit response or a specific requests-per-minute quota for any operation — see API Conventions.

Authentication recovery

When an access token is no longer usable, attempt one refresh and retry the original request once only after refresh succeeds. If refresh fails, stop and authenticate again. See Authentication and Retries and Ambiguous Outcomes.

State-changing outcomes

Do not retry Order creation blindly after an ambiguous failure; the API defines no recovery sequence for it. Label purchase is the exception — a repeat of the same purchase request replays its outcome rather than buying a second Label, and the Order carries the result. See Label Errors.

Next steps

• Choose the matching error category above and correct the reported input or authentication problem before retrying.
• Review Retries and Ambiguous Outcomes before repeating a state-changing request.
• Use Diagnostics to record safe, actionable evidence for an application-owned investigation.
• Continue to Production Readiness before go-live.
• Complete the Go-Live Checklist before relying on a production integration.