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

Auth and authorization errors:

{ "error": "Not authorized" }

Validation errors:

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

Distinguishing 403 from 404

For privacy reasons, 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"

The fix is to create a new write-scoped token; tokens are not editable in place. See Authentication.