Errors

Errors always come back in one shape. Branch on code, which is stable, rather than on message, which is written for a human and may be reworded.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Your plan allows 250 companies. You have 240 and tried to add 50."
  }
}

Authentication and subscription

Status	Code	Cause
`401`	`unauthorised`	No key, or a key that matches nothing. Check the `X-API-Key` header or `api_key` parameter.
`402`	`subscription_inactive`	The subscription lapsed. Every `/v1/` route returns this until it is reactivated, at which point the same key works again.
`403`	`account_required`	A read-only key was used on a watch or webhook route. Those need the `ask_...` account key.

Quota

Both are checked before anything is written, so a rejected request changes nothing and can be retried after you free up room or upgrade.

Status	Code	Cause
`402`	`quota_exceeded`	The request would take the account past its plan’s company limit. The message names the limit, the current count and the size of the attempted addition.
`402`	`watch_limit_reached`	The account already has as many watch lists as the plan allows.

See Getting started for the per-plan limits.

Request problems

All 400. These mean the request needs changing, so retrying it unchanged will fail identically.

Code	Cause
`empty_request`	A body was expected and none was supplied.
`empty_watch`	A watch was created with neither identifiers nor any filter. One with neither would match every notice, so it is rejected rather than accepted as a firehose.
`too_many_identifiers`	More than 50,000 identifiers in one request. Split it.
`invalid_identifier`	An identifier is not a 9-digit ACN or an 11-digit ABN. Note this is different from an identifier that is well-formed but unknown: those come back in `unresolved`, not as an error.
`invalid_acn`	A malformed ACN in a path or query parameter.
`invalid_filter`	An unrecognised filter field on a watch.
`invalid_since`	`since` was not an integer.
`invalid_date`	`from` or `to` was not `YYYY-MM-DD`.
`invalid_query`	The search query could not be parsed.
`invalid_group_by`	`group_by` was not one of `appointment_type`, `notice_purpose`, `state`, `notice_code` or `month`.
`invalid_update`	`PATCH /v1/watches/{id}` was sent a field it does not accept. It takes `active`, `name` and `alert_email` only, and the message names the offending fields.
`invalid_alert_email`	`alert_email` was neither an email address nor `null`.
`invalid_webhook_url`	The webhook URL was not an absolute `https://` URL.
`missing_url`	`POST /v1/watches/{id}/webhook` was sent without a `url`.

Routing

Status	Code	Cause
`404`	`not_found`	Unknown route, or a watch, notice or webhook that does not exist or does not belong to your account. The two are deliberately not distinguished, so the API does not confirm the existence of another account’s resources.
`405`	`method_not_allowed`	Right path, wrong verb. The message names the verb to use.

Server

Status	Code	Cause
`500`	`server_error`	Something failed on our side. Safe to retry with backoff.
`500`	`webhook_unavailable`	Webhook delivery is not configured on this deployment. Not something you can fix from the client; contact support if you see it in production.

What to retry

Retry with backoff: 500. The request was valid.
Retry after acting: 402. Reactivate the subscription, remove companies, or upgrade, then send the same request.
Do not retry unchanged: every 400, plus 401, 403, 404 and 405. These describe the request, not a transient condition.

A 404 on a company identifier is not an error in the usual sense: GET /v1/companies/{acn_or_abn} returns 200 with notice_count: 0 for a company that is in the register but has no notices. A 404 there means neither the register nor the notices table has anything for that identifier at all.