Errors

The API uses conventional HTTP status codes and always returns errors as JSON. A 2xx status means success; 4xx means the request needs changing. One 3xx is used — 300 asks you to choose between equally-valid matches (see Disambiguation).

Status Meaning When
300 Multiple Choices A bare abbreviation code matches more than one time zone.
401 Unauthorized The token is missing, malformed, or revoked.
403 Forbidden The account's email address isn't verified.
404 Not Found No resource matches the identifier in the URL.
422 Unprocessable Entity A query parameter failed validation.
429 Too Many Requests You exceeded the rate limit.

Error shape

Most errors return a single message:

{
  "message": "Unauthenticated."
}

Validation errors (422) add an errors object keyed by parameter, with an array of messages per field:

{
  "message": "The offset must look like -04:00 or bare minutes like -240.",
  "errors": {
    "offset": ["The offset must look like -04:00 or bare minutes like -240."]
  }
}

Disambiguation (300)

GET /v1/abbreviations/{code} returns 300 Multiple Choices when a bare code matches more than one named time zone (many share a code — AST, CST, …). Unlike the message-only error shape it returns a candidates list; re-request by the unique slug, or narrow with ?offset= / ?continent=.

{
  "message": "The abbreviation \"AST\" matches 2 time zones. Re-request by slug, or add ?offset= or ?continent= to disambiguate.",
  "candidates": [
    {
      "code": "AST",
      "name": "Atlantic Standard Time",
      "slug": "atlantic-standard-time",
      "continent": "Americas",
      "current": { "utc_offset": "-04:00", "is_dst": false },
      "links": { "self": "https://api.timezone.io/v1/abbreviations/atlantic-standard-time" }
    }
  ]
}

Common cases

  • 401 Unauthenticated. — Check the Authorization: Bearer <token> header. See Authentication.
  • 403 — Verify your email address, then retry. Body: { "message": "Your email address is not verified." }.
  • 404 — The IANA identifier doesn't exist. Double-check spelling and casing (America/New_York, not america/new_york), and remember to encode + as %2B.
  • 429 — Back off and retry using the Retry-After header.