Errors
All errors share a consistent envelope:
{ "error": { "code": "machine_readable_code", "message": "Human readable message." } }
Use error.code for branching in your integration; message is for humans.
Common codes
| HTTP | code | When it happens |
|---|---|---|
| 400 | invalid_post_id | The post id / URL is not a valid shortcode |
| 401 | missing_api_key | No API key supplied |
| 401 | invalid_api_key | Unknown or revoked key |
| 402 | insufficient_credit | Not enough credits for the request |
| 403 | account_inactive | The account is disabled |
| 403 | endpoint_disabled | The endpoint is disabled for your account |
| 404 | post_not_found | Post is private, deleted, or does not exist |
| 422 | validation_error | Invalid/missing query parameters |
| 429 | upstream_rate_limited | Temporary upstream throttling — retry with backoff |
| 503 | no_upstream_sessions | Data collection temporarily unavailable |
| 500 | internal_error | Unexpected server error |
Retry guidance
- 429
upstream_rate_limited— retry with exponential backoff (e.g. 1s, 2s, 4s). The API already retries internally across its session pool before surfacing this. - 503
no_upstream_sessions— transient capacity issue; retry after a short delay or contact TagX if persistent. - 5xx — safe to retry idempotent
GETrequests with backoff.
Do not retry 4xx (except 429) without changing the request.