Error codes

Every non-2xx response carries a machine-readable code and a human message:

Error shape

{
  "ok": false,
  "error": {
    "code": "document_required",
    "message": "The template has a DOCUMENT header; pass document: { url, filename }."
  },
  "request_id": "req_abc123"
}

The SDK throws a typed BluetickedError exposing code, status, and requestId — include the request id when contacting support.

Codes

Code	Meaning
`unauthorized`	Missing key, revoked key, or malformed Authorization header.
`forbidden`	The API key exists but does not have the required scope.
`not_found`	The requested contact, template, message or campaign does not exist.
`validation_failed`	The request shape is valid JSON but fails business validation.
`rate_limited`	The workspace or key exceeded a rate limit.
`idempotency_conflict`	The same Idempotency-Key was reused with a different body.
`method_not_allowed`	The endpoint does not support the attempted HTTP method.
`channel_unavailable`	The requested provider channel is disconnected or not ready.
`document_invalid`	The document parameter is malformed: url must be https and filename at most 240 characters.
`document_required`	The template has a DOCUMENT header; pass document: { url, filename }.
`document_not_applicable`	A document was supplied but the template has no DOCUMENT header (or the send is not a template send).
`document_source_invalid`	The campaign document_source is malformed; check mode, field_key, filename_template and missing_policy.
`document_source_required`	The campaign template has a DOCUMENT header; pass a document_source.
`document_source_not_applicable`	A document_source was supplied but the campaign template has no DOCUMENT header.
`internal_error`	Blueticked accepted the request but hit an internal failure.

Rate limits

Each key has a per-minute limit (default 120, configurable per key up to 10,000). 429 responses include x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset headers; the SDK retries them automatically with backoff.