Errors - Spotzee

The Extended API uses a structured error envelope served as application/problem+json (RFC 7807). Handle errors using the HTTP status and code; some fields are optional. The Main API documents the same field names, with rollout qualifications in its errors reference.

Error body shape

{
  "status": "error",
  "code": "authentication_required",
  "title": "Authentication required",
  "message": "Invalid API key. Please ensure you copied it correctly.",
  "error": "Invalid API key. Please ensure you copied it correctly.",
  "type": "https://spotzee.com/docs/main-api/errors#authentication_required",
  "request_id": "req_9f3bad665eabf0d6"
}

Field	Type	Description
`status`	string	Always `"error"` for non-2xx responses.
`code`	string	Stable, machine-readable identifier. Safe to switch on; never localised.
`title`	string	Short human-readable summary suitable for a heading. en-AU.
`message`	string	Human-readable explanation. May reference identifiers.
`error`	string	Legacy mirror of `message`. Retained while existing integrations migrate; new code should read `message`.
`type`	string	Documentation URL for this error class (RFC 7807).
`request_id`	string	Server-generated correlation ID. Echoed in the `X-Request-Id` response header. Quote it in support tickets.
`param`	string	Optional. Names the offending parameter when a single field is at fault.
`errors[]`	array	Optional. Field-level breakdown when multiple parameters fail validation. Each entry: `{ param, code, message }`.

Status codes

Status	Meaning	Typical cause
`400 Bad Request`	Invalid input	Malformed email, invalid domain, bad payload, unsupported `Spotzee-Version`
`401 Unauthorized`	Missing or invalid token	No `Authorization` header, expired key
`402 Payment Required`	Credit quota exhausted	Insufficient balance for a metered operation
`403 Forbidden`	Authenticated but not allowed	Key scope insufficient
`404 Not Found`	Resource or record not present	Domain has no DNS record of the requested type
`429 Too Many Requests`	Rate limited	Honour `Retry-After` before retrying
`500 Internal Server Error`	Unexpected platform error	Retry with backoff
`503 Service Unavailable`	Temporary capacity issue	Retry with backoff

Common error codes

The full code catalogue is shared with the Main API:

`code`	When it appears
`authentication_required`	No credential or invalid credential.
`permission_denied`	Credential lacks scope or role.
`parameter_missing` / `parameter_invalid_format`	Field absent or malformed (e.g. invalid email, bad domain).
`validation_failed`	One or more `errors[]` entries present.
`quota_exceeded`	Credit-metered operation; insufficient balance.
`rate_limited`	Token bucket exhausted; check `Retry-After`.
`version_unsupported` / `version_required`	`Spotzee-Version` header value not a known release.
`internal_error`	Unhandled. Quote `request_id` in support tickets.

Quota errors

Metered operations return 402 when available credits do not cover the operation. Check your balance in the Spotzee app before high-volume runs. The generated Extended API reference does not expose a public Quota endpoint.

Retry guidance

Reads and lookups: use bounded retries with backoff on 5xx and 429, honouring Retry-After when present. Many lookup endpoints use POST.
Metered or sending operations: inspect the endpoint’s effects before retrying. Check idempotency availability and limits; resolve input and credit errors first. The SMS group validates phone numbers and does not expose a message-dispatch endpoint.