---
title: Adi Shipping API error model
description: Stable RFC 9457-compatible JSON errors, codes, recovery hints, and rate-limit behavior for the Adi Shipping API.
canonical: https://adi-shipping.com/developers/errors/
last-updated: 2026-10-10
---

# Adi Shipping API error model

Every API failure returns a non-2xx HTTP status and `Content-Type: application/problem+json`. The body follows RFC 9457 Problem Details and adds stable `code` and `resolution` members so software agents can recover without parsing prose.

## Problem document

```json
{
  "type": "https://adi-shipping.com/developers/errors/#invalid_reference",
  "title": "Enter a valid ZIM booking, bill of lading, or container reference.",
  "status": 400,
  "detail": "Enter a valid ZIM booking, bill of lading, or container reference.",
  "instance": "/api/v1/tracking.php",
  "code": "invalid_reference",
  "resolution": "Use 1 to 40 letters, digits, dots, underscores, slashes, or hyphens."
}
```

The `type`, `title`, `status`, `detail`, and `instance` members follow RFC 9457. `code` is a stable machine-readable identifier. `resolution` gives a practical next step. Compatibility members `ok`, `message`, and `error` may also be present for existing website clients.

## Codes

- `invalid_reference` (`400`) — add or correct the shipment reference.
- `shipment_not_found` (`404`) — verify the known ZIM reference or contact Adi Shipping.
- `api_not_found` (`404`) — use a path listed in the OpenAPI contract.
- `method_not_allowed` (`405`) — use the allowed HTTP method.
- `rate_limit_exceeded` (`429`) — wait for `Retry-After` and the `RateLimit` reset value.
- `carrier_unavailable` or `carrier_response_error` (`502`) — retry later or use operational support.
- `tracking_not_configured` (`503`) — use Adi Shipping support for a confirmed update.

## Rate limits

Tracking responses include `RateLimit-Policy` and `RateLimit`. Compatibility fields `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` are also returned. A `429` response includes `Retry-After`.

## Contract

See the [OpenAPI 3.1 specification](https://adi-shipping.com/openapi.json) for the typed `Problem` schema and response references.