Errors and status codes

Status codes

Code	Meaning
200 OK	Success
201 Created	Resource created
204 No Content	Resource deleted (or no body to return)
304 Not Modified	Conditional GET with matching If-None-Match
401 Unauthorized	Missing or insufficient token (also: read token attempting a write)
403 Forbidden	Authenticated but your role doesn’t permit this action
404 Not Found	Resource does not exist or is not visible to you
422 Unprocessable Content	Validation failed

Error body shapes

Bearer-token failures (401) are not guaranteed to return JSON. The response may be empty or plain text:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Token realm="Application"

Organization-scoped authorization failures (403) and many organization-scoped hidden-resource responses (404) use:

{ "error": "Not authorized" }

Some user-scoped missing-resource responses return 404 with no body. Example: GET /me/address.json before an address exists.

Validation errors:

{ "errors": { "name": ["can't be blank"], "currency": ["is not included in the list"] } }

Distinguishing 403 from 404

For organization-scoped endpoints, the API returns 404 when:

• The resource doesn’t exist
• The resource exists but you’re not a member of the owning organization

It returns 403 only when:

• You are a member of the organization
• But your role (or other state, e.g. token scope) doesn’t allow the action

In practice: treat 403 and 404 interchangeably during retries — neither will succeed without changing the request.

Handling read-vs-write token mismatch

A read-scoped token attempting any non-GET/HEAD request returns:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Token realm="Application"

Do not rely on a JSON body here. The fix is to create a new write-scoped token; tokens are not editable in place. See Authentication.