---
title: Troubleshooting
description: 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:

```json
{
  "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](/guides/authentication) for keys and permissions, [API access](/guides/api-access) for account eligibility, and [Rate limits](/guides/retries#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](/reference) describes operation-specific outcomes and response schemas.