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 | 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) |
| 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 failed the malware/phishing check |
| 422 | destination_not_editable | Only url codes have an editable destination |
| 422 | content_not_editable | content applies to page codes only |
| 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.