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.

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​