Get started
Errors
Every failure returns the same envelope. Branch on code; messages can change without notice.
{ "error": { "code": "quota_exceeded", "message": "…" } }Status scheme: 400 malformed JSON, 401 auth, 403 plan or account state, 404 missing or not yours, 422 validation, 429 limits, 503 retryable.
Error catalog#
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_json | Request body is not valid JSON |
| 401 | unauthorized | Missing, invalid or revoked API key |
| 403 | account_suspended | The account has been suspended |
| 403 | email_unverified | Verify your account email before using the API |
| 403 | plan_required | Your plan does not include API access |
| 403 | code_limit_reached | Plan code-count limit reached (POST /codes) |
| 403 | routing_not_available | Smart rules (routing) need the Pro or Business plan |
| 404 | not_found | No code with that id in your account |
| 422 | invalid_type | type is not one of the creatable types |
| 422 | unsupported_type | PDF codes need a file upload; create them in the dashboard |
| 422 | invalid_destination | destination is not a valid http(s) URL |
| 422 | unsafe_destination | destination, or a routing rule's url, failed the malware/phishing check |
| 422 | destination_not_editable | Only url codes have an editable destination |
| 422 | invalid_routing | routing is malformed; the message names the rule and what is wrong |
| 422 | routing_not_supported | routing applies to url codes only |
| 422 | content_not_editable | content applies to page codes only |
| 422 | invalid_hours | a business page's opening hours or timezone are not in the expected format |
| 422 | invalid_profile | a social page's profile has an unknown network, or a link that is not on that network |
| 422 | invalid_layout | a gallery's layout is not grid, feed or slides |
| 422 | invalid_theme | a gallery's theme is not light or dark |
| 422 | invalid_downloads | a gallery's downloads setting is not true or false |
| 422 | invalid_coupon | a coupon's date, timezone or barcode is not in the expected format |
| 422 | invalid_store_link | an app page's store link does not point at that store |
| 422 | invalid_event | an event's date, time or timezone is not in the expected format, or it ends before it starts |
| 422 | invalid_video | a video page's video is not a YouTube or Vimeo link, or there are more than 12 |
| 422 | invalid_phone | vcard content.phone must start with + and the country code |
| 422 | invalid_status | status must be active or paused |
| 422 | empty_patch | PATCH body had no recognized fields |
| 422 | invalid_codes | bulk: codes must be a non-empty array |
| 422 | batch_too_large | bulk: more than 100 specs in one request |
| 429 | rate_limited | Burst limit: over 60 requests in 10 seconds |
| 429 | quota_exceeded | Monthly quota used up; resets on the 1st (UTC) |
| 503 | slug_unavailable | Could not allocate a short link; retry the request |
Retries#
Requests are not idempotent. A network retry of a POST can create a duplicate code; on timeout, list your codes before retrying. 503 slug_unavailable is safe to retry after a short delay.