Copy page

Getting started

Errors

Errors

One shape, whatever went wrong:

Code
{
  "error": {
    "code": "invalid_status",
    "message": "Unknown status \"bidon\"."
  }
}

code is stable and meant to be branched on. message is a sentence for a human and may be reworded — never match on it.

The codes

Status	Code	What it means
400	invalid_body	The body is not a JSON object.
400	invalid_status, invalid_priority	A value outside the allowed set.
400	invalid_cursor	The cursor is not one we handed out.
400	invalid_assignee, invalid_organization, invalid_category	An id that belongs to no such object in this workspace.
400	empty_patch	A PATCH with nothing to change.
401	unauthorized	Missing, malformed, unknown or revoked key.
403	forbidden	The key lacks the scope this route needs.
403	workspace_suspended	The workspace is suspended; nothing is served.
403	requester_blocked	The contact is blocked from opening tickets.
404	not_found	No such object in this workspace.
409	email_taken, slug_taken	A unique value already belongs to another row.
409	contact_has_tickets	Deleting would erase a support history; ask for it explicitly.
429	rate_limited	Over 600 requests a minute. Retry-After says how long.
500	internal_error	Ours. Retry, and tell us if it persists.

What to retry

• 429 — yes, after Retry-After.
• 500 — yes, with backoff. Twice, then raise it rather than hammer.
• 4xx anything else — no. The request will fail identically until you change it; retrying only fills your logs and our rate limit.

A note on 404

A 404 means "not in this workspace", not "does not exist anywhere". An id from another workspace is indistinguishable from one that was never created, and deliberately so: the API must not confirm that someone else's ticket exists.