Errors

The Main API returns standard HTTP status codes and a structured error body for every non-2xx response. The body is the RFC 7807 Problem Details envelope with a few Spotzee-specific extensions, served with Content-Type: application/problem+json.

The canonical envelope is live for every error on apix.spotzee.com/api/client/*, apix.spotzee.com/api/admin/*, and the Extended API. Edge rate-limit 429 responses also use this envelope. Build your client around the string code field — it’s the stable, machine-readable identifier.

Numeric code values are deprecated. Earlier releases occasionally returned numeric values like 1007, 6000, or 9000 in the code field. Those came from legacy internal catalogues and were never part of the public contract. Never switch on them. The current API returns only the string codes from the catalogue below; if you ever see a numeric code, treat it as an unrecognised error and key off the HTTP status instead.

Error body shape

{
  "status": "error",
  "code": "resource_missing",
  "title": "Resource missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "type": "https://spotzee.com/docs/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": []
}

Once the rollout completes, error responses set Content-Type: application/problem+json.

Field	Type	Description
`status`	string	Always `"error"` for non-2xx responses
`code`	string	Stable, machine-readable identifier from the catalogue below
`title`	string	RFC 7807 short title. Same for every response with this `code`.
`message`	string	Human-readable explanation, may include identifiers; safe to display in logs
`type`	string	URL of the docs entry for this `code`
`request_id`	string	Per-request correlation id (also returned as the `X-Request-Id` response header)
`param`	string	Optional. Names the offending parameter (e.g. `id`, `Spotzee-Version`).
`errors`	array	Optional. Per-field validation breakdown when multiple fields are invalid.

Per-field errors

When code is validation_failed, the errors array lists every offending field:

{
  "status": "error",
  "code": "validation_failed",
  "title": "Request validation failed",
  "message": "One or more fields failed validation. See errors[] for details.",
  "type": "https://spotzee.com/docs/main-api/errors#validation_failed",
  "request_id": "req_01HXY…",
  "errors": [
    { "param": "email", "code": "parameter_invalid_format", "message": "Must be a valid email address" },
    { "param": "external_id", "code": "parameter_missing", "message": "Required" }
  ]
}

Status codes

Status	Meaning	Typical cause
`400 Bad Request`	Malformed request	Invalid header value, malformed JSON, bad parameter format
`401 Unauthorized`	Missing or invalid credential	Missing `Authorization` header, expired or revoked key
`402 Payment Required`	Quota exhausted	Credit-metered operation with insufficient balance
`403 Forbidden`	Authenticated but not allowed	Key lacks the role for this resource
`404 Not Found`	Resource missing	Wrong id, resource deleted, or scoped to a different project
`409 Conflict`	State conflict	Unique-constraint violation, idempotency mismatch
`422 Unprocessable Entity`	Validation failed	One or more fields failed schema validation
`429 Too Many Requests`	Rate limited	Honour the `Retry-After` header before retrying
`500 Internal Server Error`	Unexpected error	Retry with backoff; if persistent, include the `request_id` when contacting support
`503 Service Unavailable`	Temporary capacity issue	Retry with backoff

Code catalogue

The code field is stable and documented. Add new codes to your switch statement only when you need to handle them differently. The catalogue is additive.

`code`	HTTP	Meaning
`resource_missing`	`404`	The referenced resource does not exist or isn’t visible to this key
`resource_already_exists`	`409`	Unique-constraint violation on create
`state_conflict`	`409`	Resource state does not permit the requested operation
`parameter_missing`	`400`	A required field is absent
`parameter_invalid_empty`	`400`	A required field is present but empty
`parameter_invalid_format`	`400`	A field is present but malformed
`parameter_unknown`	`400`	A field isn’t recognised by this version
`validation_failed`	`422`	One or more entries are returned in `errors[]`
`authentication_required`	`401`	No credential or invalid credential
`permission_denied`	`403`	Credential lacks the role for this resource
`idempotency_key_mismatch`	`409`	Same `Idempotency-Key` replayed with a different body
`idempotency_key_invalid`	`400`	Empty or longer than 255 characters
`idempotency_in_progress`	`409`	Original request still running. Retry after `Retry-After`.
`rate_limited`	`429`	Rate limit exceeded. Honour `Retry-After`.
`version_unsupported`	`400`	`Spotzee-Version` value is not a known release
`version_required`	`400`	Endpoint requires a pinned version (rare)
`webhook_signature_invalid`	`400`	HMAC verification failed on inbound webhook configuration
`quota_exceeded`	`402`	Credit-metered operation with insufficient balance
`service_unavailable`	`503`	Temporary capacity or lock contention. Retry with backoff.
`internal_error`	`500`	Unhandled platform error. Report the `request_id`.

Retry guidance

Idempotent reads (GET): retry freely on 5xx and 429.
Mutations (POST / PATCH): include an Idempotency-Key header so retries are safe. Retry on 5xx and 429; do not retry 4xx (with the exception of idempotency_in_progress, which is explicitly retryable).

Reporting bugs

Always include the request_id (in the response body or the X-Request-Id header) when reporting an error. It lets us trace your specific request end-to-end.

Next steps

Idempotency

Make retries safe.

Rate limits

Avoid 429 with self-throttling.

Overview

Projects

Events

Campaigns

Lists

Subscriptions

Journeys

Templates

Users

Tags

API keys

Organisation

Billing recovery

Webhooks

CRM

Source Sync

Form definitions

Form submissions

Error body shape

Per-field errors

Status codes

Code catalogue

Retry guidance

Reporting bugs

Next steps

Idempotency

Rate limits

​Error body shape

​Per-field errors

​Status codes

​Code catalogue

​Retry guidance

​Reporting bugs

​Next steps

Idempotency

Rate limits

Error body shape

Per-field errors

Status codes

Code catalogue

Retry guidance

Reporting bugs

Next steps