Errors

Use the HTTP status and the string code field to handle Main API errors. The documented error shape follows RFC 7807 Problem Details with Spotzee-specific fields. Clients must also handle responses that omit optional fields or use application/json during the conventions rollout.

Use the HTTP status as a fallback when a response has no recognised string code. Include X-Request-Id when reporting a failed request.

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	Honour `Retry-After` when present, then 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
`archived_user_conflict`	`409`	The contact is archived; resolve its recovery state before retrying
`user_capacity_exhausted`	`409`	The organisation has no capacity for another active contact
`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

Reads (GET): use bounded retries with backoff on 5xx and 429. Honour Retry-After when present.
Mutations (POST / PATCH): check idempotency availability and limits before retrying. A timed-out request may have taken effect. Resolve validation or permission errors before retrying; idempotency_in_progress explicitly permits a delayed retry.

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

Users

CRM

Source Sync

Events

Lists

Subscriptions

Templates

Campaigns

Journeys

Tags

API keys

Organisation

Webhooks

Billing recovery

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