Errors

Every error returns a real HTTP status and this body:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key is missing the 'analytics:read' scope.",
    "required_scope": "analytics:read"
  }
}

Branch on code, never on message. Codes are stable. Messages are written for humans and may be reworded.

Codes

unauthorized (401)

No credential was supplied. Add the Authorization header.

invalid_key (401)

The key is malformed or unknown. Check for a truncated copy and paste.

expired_key (401)

The key passed its expiry. Create a new one.

revoked_key (401)

The key was revoked in Settings. Create a new one.

insufficient_scope (403)

The key is valid but lacks the scope this endpoint needs, and required_scope names it. Do not rotate the key, it is fine. Create one with the right scopes.

invalid_parameter (400)

A query parameter was out of range or not one of the allowed values. param names it.

not_found (404)

No object with that id, or it exists but does not belong to your account. These return the same answer on purpose: whether another account holds a given record is not something this API will confirm.

rate_limited (429)

Too many requests this minute. Retry-After tells you how many seconds to wait.

internal_error (500)

Something failed on our side. Retry with backoff. If it persists, mail work@ashwanth.dev with the time of the request.

Retrying

Retry 429 and 500. Do not retry 400, 401, 403, or 404: they will fail identically until you change the request or the key.