Error Codes

Every error returns the same JSON envelope: a success: false flag, a nested error object, and a request_id naming the request that failed. The error object always carries the HTTP status the response was written with, a numeric code, and a human-readable message.

{
  "success": false,
  "error": {
    "status": 422,
    "code": 1001,
    "message": "Field required.",
    "doc_url": "https://docs.linqapp.com/channel/whatsapp/error/codes/1xxx/1001/",
    "param": "/parts/0/body",
    "details": [
      {
        "code": "field_required",
        "param": "/parts/0/body",
        "message": "Body is required."
      }
    ]
  },
  "request_id": "req_01JQZ8X4K2N3P5R7T9V1W3Y5Z7"
}

error.code is a number and is the field to branch on. error.message is written for a human reading a log and may be reworded at any time, so matching on it will break. A code is never removed and never reassigned to a different failure: once a number means something, it means that forever.

The optional members carry the specifics. param is present only when the response is about exactly one field and is that field’s JSON Pointer; with zero or several faults it is absent. details lists every field-level finding on a validation failure, each with a string code, a JSON Pointer param and a message. retry_after is present exactly when the response also carries a Retry-After header, with the same value in seconds. trace_id appears when a valid trace context exists. doc_url is present on every response whose code has a published page and is the absolute address of that page, https://docs.linqapp.com/channel/whatsapp/error/codes/<N>xxx/<code>/, so a client can link straight to it; it is derived from the code alone, and a code reachable only on a surface that has not been released yet carries no doc_url.

These codes belong to WhatsApp. Every channel numbers its own errors, which is why this reference is namespaced to /channel/whatsapp/ — the same integer means something different on another channel, so branch on the code only in code paths you know are talking to this API.

The set of codes grows over time. Branch on the integers you know, and treat an integer you do not know by its range plus the HTTP status that came with it — the range says what kind of failure it is, and the status says whether the request or the service was at fault.

When retry_after is present, it overrides the guidance above: wait that many seconds, then retry.

The request never reached the thing it was about. Correct the request and send it again; retrying it unchanged fails identically. Validation rejects and points at the most specific location it can identify — it never coerces a value into something acceptable.

The request was well formed and the thing it named was missing, not yours, or not in a state that allows this. Inspect or reconcile that state before sending again.

An id that belongs to another account answers exactly like one that does not exist. That is deliberate: it keeps one account from probing another’s ids.

Transient, and ours. Retry with bounded exponential backoff, starting at 1 second and capping at 30, unless the code’s own page says otherwise. Sends are idempotent on Idempotency-Key, so a retry of a send that actually succeeded returns the original result rather than sending twice.

The send was understood and refused for an operational reason: a sending number that cannot carry it, a paused account, or a limit that was reached. Each code names its own remedy; a retry without that remedy is refused the same way.

The file’s bytes: its kind, its size, where it came from, or storing it. An attachment that is merely missing or not yet readable is a 2xxx resource error instead.