Error Reference

Every error response is JSON with a stable error code and a human-readable message. The HTTP status mirrors the category.

Format

{
  "error":   "slug_taken",
  "message": "The slug 'launch' is already in use"
}

Codes

code	HTTP	meaning
unauthorized	401	Missing or invalid API key.
forbidden	403	Key exists but doesn't own this resource.
not_found	404	No short link with that code.
slug_taken	409	The custom_code you asked for is already in use.
invalid_url	422	The destination URL did not parse.
rate_limited	429	You hit your tier's quota — back off and retry.
server_error	500	Something broke on our side. Retry with exponential backoff.

Retrying

4xx errors are deterministic — fix the request and retry. For rate_limited the response includes a Retry-After header in seconds. For 5xx, retry with exponential backoff (250ms · 500ms · 1s · 2s · 4s, max 5 tries).