Errors
Error Handling
v1 routes return consistent JSON envelopes from https://api.shortify.com. Log the request ID with your integration errors so Shortify support can trace the request.
Error Envelope
400
Validation error{
"success": false,
"error": {
"code": "invalid_url",
"message": "Destination URL must start with http:// or https://."
},
"requestId": "req_01HV4Z4Y6W3D4J9B2Y8QH6P8JS"
}Status Codes
| Status | Meaning |
|---|---|
| 400 | Validation error, malformed JSON, invalid query parameter, or invalid request field. |
| 401 | Missing, inactive, or invalid API key. |
| 403 | Credential type or key scope is not allowed for the route. |
| 404 | Resource was not found or does not belong to the authenticated workspace. |
| 409 | Duplicate short link or Idempotency-Key reuse with a different body. |
| 415 | Request body was sent with a non-JSON content type. |
| 500 | Unexpected server error. |
| 503 | Analytics is not configured, unavailable, or not initialized. |
Retry Guidance
Safe retries
Use Idempotency-Key on create requests. Reusing the same key with the same body returns the stored response.
Fix before retry
Do not retry 400, 401, 403, 404, 409, or 415 without changing credentials or request data.
Temporary failures
Retry 500 and 503 with exponential backoff. Analytics 503 does not affect link inventory APIs.