Troubleshooting

Read response envelopes and troubleshoot HTTP errors.

JSON responses contain success, an English message, data, and a server-generated requestId. Failures also contain errorCode and errors; data is null. Share requestId with support to identify an attempt.

This HTTP 400 example reports a missing idempotency header:

{
  "success": false,
  "message": "Request validation failed.",
  "data": null,
  "requestId": "<request-id>",
  "errorCode": "BAD_REQUEST",
  "errors": {
    "fields": [
      {
        "path": "Idempotency-Key",
        "errorCode": "required",
        "message": "Idempotency-Key is required."
      }
    ]
  }
}

Common errors

These errors apply across the API. Endpoint pages show operation-specific responses; the downloadable OpenAPI specification includes all possible responses.

HTTP	Meaning and next action
`401`	`UNAUTHORIZED`: supply a valid Customer API key; check revocation and the environment.
`403`	`FORBIDDEN`: check API enablement, active invoice-account eligibility, and the required key permission.
`429`	`TOO_MANY_REQUESTS`: wait `errors.retryAfterSeconds` before retrying.
`500`	`INTERNAL_SERVER_ERROR`: contact support with `requestId`. Keep the mutation key if you retry.
`503`	`SERVICE_UNAVAILABLE`: retry later with the same mutation key.

See Authentication for keys and permissions, API access for account eligibility, and Rate limits for limits and retry timing.

Endpoint errors

HTTP	Meaning and next action
`400`	Correct input using `errors.fields`. Check service/route availability for `ROUTE_UNAVAILABLE`, label support for `LABEL_NOT_SUPPORTED`, or the selected shop for `INVALID_PICKUP_LOCATION`.
`404`	`NOT_FOUND`: check the resource ID or list cursor and the account associated with your key.
`409`	Inspect `errorCode` and `errors`. Check the endpoint’s Prerequisites and Behavior sections, and the idempotency guide, before retrying.

503 PICKUP_LOCATIONS_UNAVAILABLE means a GLS shop lookup cannot complete. Retry later. Keep the same idempotency key for shipment writes.

errors is null when no details apply. Validation entries contain path, errorCode, and message, with at most one issue per field path. Price conflicts use errors.price; state conflicts can include errors.currentStatus. The API reference describes operation-specific outcomes and response schemas.