Errors

The Lynkist Public API uses standard HTTP status codes and a small, predictable JSON body. This page describes the envelopes you actually receive today, the HTTP codes you should plan for, and the headers that help you correlate, retry, and back off.

Error envelope

Every error response uses the same JSON envelope:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Contact not found"
  },
  "meta": {
    "request_id": "req_04673bffe2ed",
    "timestamp": "2026-06-28T05:22:51.953Z"
  }
}

• error.code — a stable, machine-readable code from the list below. Branch on this, not on the message. A code and its HTTP status do not change inside a major version (Versioning).
• error.message — a sentence for a person. It can change.
• meta.request_id — the same value as the X-Request-Id header. Log it; quote it in tickets.

Some codes add extra fields beside code and message. A missing scope lists what was required and what the key has:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Missing required scope(s): campaigns:send",
    "required_scopes": ["campaigns:send"],
    "granted_scopes": ["campaigns:read", "campaigns:write"]
  },
  "meta": { "request_id": "req_…", "timestamp": "…" }
}

Other examples: UPGRADE_REQUIRED adds upgrade_required: true and feature_key; RATE_LIMIT_EXCEEDED adds window and retry_after; a send error adds retryable; VALIDATION_ERROR adds a details list (see below).

Standard response headers

Every response — success or error — carries:

See Rate Limits for the full backoff guidance.

HTTP status codes

A failure on our side is always 5xx, never 4xx. So the rule for a client is simple: retry 5xx and 429 with exponential backoff, and never retry another 4xx unchanged.

Error codes

An error with no specific code has the code of its status: INVALID_REQUEST (400), NOT_FOUND (404), CONFLICT (409), UPSTREAM_ERROR (502), and so on. UPGRADE_REQUIRED is always 403 (your plan does not include the feature); a plan limit is 429 PLAN_LIMIT_REACHED.

A request with no Authorization header answers 401 AUTHENTICATION_REQUIRED with the message Not authenticated.

Send errors

POST /messages/template can answer with one of the send codes above (RECIPIENT_UNDELIVERABLE, TEMPLATE_REJECTED, SEND_RATE_LIMITED, WHATSAPP_UNAVAILABLE, …). Each has retryable:

{
  "success": false,
  "error": {
    "code": "WHATSAPP_UNAVAILABLE",
    "message": "WhatsApp sending is temporarily unavailable. Wait a moment, then send the message again.",
    "retryable": true
  },
  "meta": { "request_id": "req_…", "timestamp": "…" }
}

Validation errors (400 VALIDATION_ERROR)

The rejected fields are in error.details. Each entry names the field, a machine-readable code and a message. The values that you sent are never returned.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid fields.",
    "details": [
      { "field": "to", "code": "missing", "message": "Field required" }
    ]
  },
  "meta": { "request_id": "req_…", "timestamp": "…" }
}

A nested field has a dotted path, for example contacts.0.phone.

Rate limiting (429 RATE_LIMIT_EXCEEDED)

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please slow down.",
    "window": "minute",
    "retry_after": 17
  },
  "meta": { "request_id": "req_…", "timestamp": "…" }
}

Wait the number of seconds in the Retry-After header, then try again. See Rate Limits.

Handling errors well

• Don't pattern-match on the human message. Messages are written for people and may change. Match on the HTTP status and error.code, plus — for 403 — the extra fields in error.
• Log X-Request-Id on every failure. It is the single fastest signal we can correlate against on our side. Include it in support tickets and bug reports.
• Retry only what is safe. Retry 5xx and 429 with exponential backoff (for example 1 s, 2 s, 4 s, … with some random jitter, and a maximum number of attempts), and obey Retry-After. Another 4xx does not pass on a retry. A retry loop with no backoff makes an outage longer.
• Pair retries with Idempotency-Key. A retried POST without an idempotency key risks creating duplicate resources. See API Reference.
• Treat IP_NOT_ALLOWED as fatal. A network move is the only fix; retrying from the same IP will fail forever.