Errors - A-Char API

Errors return a JSON body with a stable code and status:

{
  "defined": false,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "A department with name Finance already exists",
  "data": { "shouldDisplay": true }
}

Status codes

Status	Code	Means
`400`	`BAD_REQUEST`	Invalid input, or a rule the request breaks — such as a duplicate name
`401`	`UNAUTHORIZED`	Missing, malformed, revoked or expired key
`403`	`FORBIDDEN`	The key is valid, but lacks the scope this operation needs — or your role does not permit it
`404`	`NOT_FOUND`	No such record in your organization
`500`	`INTERNAL_SERVER_ERROR`	A fault on our side — safe to retry

Showing messages to your users

data.shouldDisplay marks a message as written for a person to read. When it is true, the message explains something the caller can fix and is safe to surface as-is. When it is absent, the message is diagnostic — log it, and show your own wording instead.

A note on 403

A 403 is returned before the operation runs, so nothing changed and no record was touched. It also means a key cannot use error codes to discover which records exist: deleting a record you lack the scope for returns 403, not 404, whether or not that record is real.

Absent records

Fetching a single record that does not exist returns 200 with a body of null, not a 404. Updating or deleting one returns 404, because acting on a record that is not there is a different situation from looking for one that might not be.

​Status codes

​Showing messages to your users

​A note on 403

​Absent records

Status codes

Showing messages to your users

A note on 403

Absent records