Errors

Every error has a stable code and a readable message.

Embed
Preview of the card
<a href="https://forumulate.com/p/trackified/docs/errors"><img src="https://forumulate.com/api/public/orgs/trackified/spaces/docs/pages/3987d966-878f-4984-a799-9344f6967e64/social-card.svg?v=3e7ae33eec8b" alt="Errors" width="600" height="315"></a>

Errors return JSON with a stable code you can branch on and a message written for people:

{ "error": { "code": "unauthorized", "message": "missing or invalid API key", "request_id": "req_..." } }

Status

Code

What to do

400

bad_request

Fix the request body or query; the message names the field.

401

unauthorized

The API key is missing, wrong or revoked.

402

quota_exceeded

You've used this month's trackings. Upgrade, or wait for the next month.

404

not_found

No tracking, webhook or key with that id on your account.

409

idempotency_in_progress

A create with this Idempotency-Key is still running. Retry in a few seconds.

422

carrier_not_supported

We don't track that carrier yet. We record the request, and it moves that carrier up our build queue.

422

carrier_not_detected

We can't tell the carrier from the number alone. Send carrier explicitly.

422

idempotency_key_reused

This Idempotency-Key was already used with a different body. Use a new key.

429

rate_limited

Too many requests. Wait for the Retry-After seconds, then retry.

Anything in the 5xx range is on our side: retry with backoff, and include the request_id if you contact us.

Retrying a create safely

Send an Idempotency-Key header on POST /v1/trackings (a UUID, or your own order id). For 24 hours, a retry with the same key and body returns the tracking the first request created, with Idempotent-Replayed: true, instead of adding a second one:

curl -X POST https://api.trackified.15-204-158-166.sslip.io/v1/trackings \
  -H "Authorization: Bearer $TRACKIFIED_KEY" \
  -H "Idempotency-Key: order_1042" \
  -H "Content-Type: application/json" \
  -d '{"tracking_number": "1Z999AA10123456784", "custom_id": "order_1042"}'

Without a key, find what a timed-out request made by your own reference: GET /v1/trackings?custom_id=order_1042 (or ?tracking_number=…).

Watching your quota

GET /v1/account/usage returns trackings_used, trackings_limit and trackings_remaining for the current month (UTC), with period_end saying when it resets. Check it before a create fails with 402 quota_exceeded.

Updated