Errors

When a request can't be done, the answer has a status code of 400 or more and a JSON body saying why.

The error body

{
  "error": "Please check the highlighted fields.",
  "code": "AbsenceOverlap",
  "fields": { "name": "Required" }
}

Field	What it is
`error`	Always there. A sentence written for a person; fine to show to your users.
`code`	Sometimes there. A fixed word your code can act on, such as `ModuleDisabled`. Codes don't change; the sentence might.
`fields`	On a 400 when the request didn't pass checks: each wrong field with what was wrong. Nested fields are joined with dots, such as `lines.0.quantity`.

Status codes

Status	Meaning
`400`	The request is wrong: a missing or badly formed field (see `fields`), or something that doesn't make sense, such as a finish before a start.
`401`	No key, or the key isn't valid any more.
`403`	The key's role isn't allowed to do this, or the part of Workscope is switched off or kept from the key (see the codes below).
`404`	Not found, or not something this key can see. Another company's records always answer 404.
`409`	It clashes with how things are now, such as changing an invoice that has been issued. The `code` says which clash.
`429`	Too many requests. Wait and try again (see below).
`500`	Something went wrong on our side. Try again; if it keeps happening, tell us.

Codes you may see

Code	When
`ModuleDisabled`	That part of Workscope (for example invoicing) is switched off for the company.
`ModuleHidden`	The part is switched on, but kept from this key or login.
`CompanySettingsHidden`	Company settings are kept from this key or login.
`KeyNotAllowed`	Keys can't make this request: it needs a person logged in (see Keys and roles).
`ReadOnlyKey`	A read-only key tried to change something.
`TooManyAttempts`	A rate limit was reached.
Others, such as `AbsenceOverlap`, `InvoiceVoid`, `QuoteLocked`, `TimesheetOverlap`	A 409 clash. The `error` sentence explains it.

Rate limits

Each key can make 600 requests a minute. Some things have tighter limits of their own: uploads (300 an hour per login or key), imports (60 an hour per company) and emails a company sends (120 an hour).

Past a limit, you get 429 with the code TooManyAttempts and a sentence saying how long to wait. Where there's a Retry-After header, wait that many seconds before trying again. Otherwise back off, starting at a few seconds and doubling each time.