Errors

The shape

Every refusal is a problem document.

{
  "type": "https://api.droomwork.com/errors/not_found",
  "code": "not_found",
  "title": "No record with that identifier",
  "detail": "No payroll_run with identifier 'run_enterprise_01J8...'.",
  "request_id": "req_01M20C7SAMXRPKTZYSVNFDZFJ3"
}

Branch on code. Once published it's stable for ever. title and detail are for a person reading a log: we write them to be clearer over time, so they'll change, and code that matched on them would break.

Not found rather than forbidden

A record belonging to another organisation answers not_found, the same as one that never existed.

Don't read not_found as proof a record doesn't exist. Answering forbidden would confirm it does, and we don't confirm that to somebody who can't read it.

Every code, and who returns it

The error index lists every code you can get back, what it means, what to do about it, and which endpoints return it. Each endpoint in the reference lists its own.

Two codes are published and not yet returned by anything: rate limiting is described in the catalogue and isn't enforced today. They're listed rather than hidden so you can handle them before they start happening.