Errors & Status Codes
Comprehensive guide to Shortyy standardized JSON error envelope, error codes, and troubleshooting steps.
Errors & Status Codes
Shortyy returns standard HTTP status codes along with a consistent, typed JSON error envelope across all REST endpoints. Direct HTTP clients and SDKs can reliably inspect error.code and error.status.
Standardized Error Envelope
All error responses adhere to this structure:
json
{
"error": {
"code": "INVALID_URL",
"message": "The provided destination URL must use http:// or https:// protocol.",
"status": 400,
"details": {
"field": "url"
}
}
}Canonical Error Codes
| Status Code | Error Code | Description | Corrective Action |
|---|---|---|---|
| 400 | MALFORMED_JSON | Request body contains invalid JSON syntax. | Ensure valid JSON syntax with escaped strings. |
| 400 | VALIDATION_FAILED | Required fields are missing or fail type checks. | Check request parameters and types. |
| 400 | INVALID_URL | Target URL is not a valid absolute HTTP/HTTPS URL. | Prefix with https:// and ensure hostname is valid. |
| 401 | UNAUTHORIZED | Missing Authorization or X-API-Key header. | Supply valid Bearer token. |
| 401 | INVALID_API_KEY | Supplied API key does not match or has expired. | Generate a new key from the developer keys portal. |
| 403 | FORBIDDEN | Key lacks necessary scope or plan entitlement. | Verify scopes or upgrade subscription tier. |
| 404 | LINK_NOT_FOUND | Link ID or short code does not exist. | Confirm the UUID or short code exists and belongs to you. |
| 409 | CODE_ALREADY_EXISTS | Custom short code is already claimed or reserved. | Select an alternative custom code. |
| 415 | INVALID_CONTENT_TYPE | Payload sent without Content-Type: application/json. | Include Content-Type: application/json header. |
| 429 | RATE_LIMIT_EXCEEDED | Token bucket exhausted. | Wait retryAfterSeconds before re-requesting. |
| 500 | INTERNAL_SERVER_ERROR | Internal system error. | Retry with exponential backoff; contact support. |