Skip to main content

Diagnostics

Safe fields to record​

Where available and relevant, record the operation ID or application operation name, method/path template, HTTP status, timestamp, application-generated internal request identifier, retained Order/Shipment/Rate/Label identifiers, Account/Sub-account selection used by your application, public error code/message, download Content-Type, and client-owned retry count.

Fields not to log​

Do not log API keys, bearer or refresh tokens, Authorization headers, full personal addresses/contact data, raw Label binary, private carrier/provider payloads, secrets, or full request/response bodies by default.

Correlation IDs​

The current public API contract does not define a Mailhub correlation/request ID header. Generate an application-generated internal request identifier when it helps your own diagnosis, but do not expect Mailhub to echo it.

That is about headers. An individual response body may still carry diagnostic identifiers of its own: a Label-purchase 202 returns operationId and correlationId. Record them with the rest of your evidence if they help — no public operation accepts either value back, so neither queries nor reconciles the purchase.

Operational diagnosis​

  • Authentication failure: follow Authentication Errors.
  • Validation failure: correct the input using Validation Errors.
  • Inaccessible Sub-account: inspect operation-specific behavior in Work with Sub-accounts.
  • V2 no-Rate 422: keep it distinct from invalid input; do not blindly repeat an outcome that may follow Order persistence.
  • Label purchase or cancellation ambiguity: preserve sanitized context and use a client-owned controlled process, not an invented API reconciliation flow.
  • Download 202: treat it as pending/still generating without a fixed cadence.
  • Server failure: record the public status and bounded envelope when present; do not assume a retry changes the outcome.

Next steps​