Errors

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "\"loyalty_tier\" is not a defined custom field. Valid keys: none defined.",
    "details": {
      "field": "loyalty_tier",
      "code": "unknown_custom_field"
    },
    "next_steps": [
      {
        "action": "correct_request",
        "by": "caller",
        "description": "The message names the offending field. Fix it and retry; the same body will fail again."
      }
    ]
  },
  "request_id": "req_ca7d43c17cab7ea1c60aa97a8c2668ca"
}

Branch on code, never on message: messages are prose and may be reworded. The request_id is also on the x-request-id header, and it identifies the exact call in your request log; quote it in support requests.

next_steps is always present and never empty. Each step carries a stable action to branch on, a sentence for your logs, and (the part worth writing code against) by, which says who can clear the failure: caller means you can fix it yourself and retry, human means a person has to act in a browser (surface it and stop retrying: no rewrite of the request will help), and waiting means something outside anyone's control, such as a Meta review, so poll. Steps that are fixed by a call carry endpoint; steps a person must clear carry url.

When the body does not fit the schema, details is the list of schema issues, each with the field's path and a message. When the body fits but a value breaks a rule, details names the field.

POST /api/v1/messages
{
  "channel": "whatsapp",
  "body": "Hello"
}

HTTP 400
{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "Invalid message: `to` — Invalid input: expected object, received undefined",
    "details": [
      {
        "expected": "object",
        "code": "invalid_type",
        "path": [
          "to"
        ],
        "message": "Invalid input: expected object, received undefined"
      }
    ],
    "next_steps": [
      {
        "action": "correct_request",
        "by": "caller",
        "description": "The message names the offending field. Fix it and retry; the same body will fail again."
      }
    ]
  },
  "request_id": "req_3a0a501cdcc36329614c739fe760383f"
}

POST /api/v1/contacts
{
  "phone": "+27800000001",
  "custom_fields": {
    "loyalty_tier": "gold"
  }
}

HTTP 400
{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "\"loyalty_tier\" is not a defined custom field. Valid keys: none defined.",
    "details": {
      "field": "loyalty_tier",
      "code": "unknown_custom_field"
    },
    "next_steps": [
      {
        "action": "correct_request",
        "by": "caller",
        "description": "The message names the offending field. Fix it and retry; the same body will fail again."
      }
    ]
  },
  "request_id": "req_ca7d43c17cab7ea1c60aa97a8c2668ca"
}

With a test key, ask for a failure by its code and get the real response: the real status, code and next_steps.

curl "https://app.blueticked.com/api/v1/channels" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY" \
  -H "X-Simulate-Error: channel_unavailable"

Test keys only: a live key that sends the header is refused, so a test suite cannot pass against production while proving nothing. The header is read after authentication and rate limiting, so it uses quota like any other call. The codes you can ask for:

channel_unavailable, insufficient_balance, spend_cap_reached, rate_limited, plan_limit_reached, subscription_inactive, queue_unavailable, service_unavailable, provider_error, validation_failed, idempotency_conflict, resource_in_use, not_found, forbidden

Two you will meet early:

rate_limited

details.scope says which bucket refused the call: "key" (this key's own allowance) or "organization" (the plan allowance every key shares), so you know whether to slow one worker or the whole fleet. details.limit is that bucket's ceiling and details.reset_at (ISO 8601) when it refills.

insufficient_balance

details.estimated_cost_zar_cents is what the send would cost, details.balance_zar_cents the purchased top-up balance, and details.available_zar_cents what the send can draw on: the plan's included credit plus the top-up (plus a small grace for a transactional send). All in ZAR cents.

This list is the same one the OpenAPI Error enum is generated from, so it cannot fall behind the API.

96 reasons today; a value not listed here means the code's general case.

Two answers forward a reason from elsewhere, so their values are open-ended:

• POST /api/v1/templates/{id}/submit (internal_error): The submit pipeline's own snake_case reason (for example meta_unreachable when Meta could not be reached).
• POST /api/v1/messages (queue_unavailable): The send queue's own error text, when a message could not be handed to the queue. Nothing was sent.