Errors

Every failure on /api/v1 comes back in the same envelope, with a code drawn from a closed set of nine. That uniformity is the point: one error handler covers the entire API, and you never have to guess whether a given endpoint reports failure differently.

The interesting part is details.reason. The code tells you the class of problem — is this my fault, your fault, or a precondition? — and the reason tells you exactly which problem it is. Handle both, in that order.

The envelope #

{
  "error": {
    "code": "failed_precondition",
    "message": "This workspace has no WhatsApp sender connected.",
    "details": { "reason": "channel_not_connected" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}

Five fields, always present.

The console's request log (Developers → Logs) shows the time, method and path, key, status with the error code, and duration of requests made with a valid key. It does not show request_id or correlation_id, so keep them in your own logs. Requests refused before the key is accepted (a 401, a workspace_suspended 403, or a rate_limited 429) are not recorded there at all.

Code to HTTP status #

Nine codes. No tenth code can exist: the error type rejects any value outside this map at construction time.

Note the two that surprise people:

• 412, not 501 or 503, for "this can't happen here yet". A 412 says the precondition for your request is unmet: no WhatsApp sender connected, no phone number on the workspace, the month's allowance and credits used up. The request would be perfectly valid once that precondition is met, and repeating it unchanged will keep failing until a human changes something in the console.
• 403 for a foreign resource, occasionally. Most cross-workspace access is answered with 404: a call, conversation, or ticket belonging to another workspace reads as "not found" rather than "not yours", which leaks nothing about whether the id exists. The exception is from_number on a call, where a 403 is the honest answer to "that number is not yours".

Validation failures are 400, not 422 #

If you have used other Python-backed APIs you may expect a 422 Unprocessable Entity for schema violations. This API returns 400 with code: "invalid_argument", so that field-level validation and hand-written rules land in the same branch of your handler.

{
  "error": {
    "code": "invalid_argument",
    "message": "Request validation failed.",
    "details": {
      "errors": [
        {
          "loc": ["body", "to"],
          "msg": "String should match pattern '^\\+?\\d+$'",
          "type": "string_pattern_mismatch"
        },
        {
          "loc": ["body", "template", "name"],
          "msg": "String should have at least 1 character",
          "type": "string_too_short"
        }
      ]
    },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}

The shape:

• message is always the literal "Request validation failed." — the useful detail is in details.errors.
• details.errors is an array, so several bad fields are reported at once rather than one per round trip.
• Each entry has loc (the path to the offending field, starting with "body" or "query"), msg (a human sentence), and type (a stable machine token like string_too_short, missing, greater_than_equal).

Note that a validation 400 has no details.reason: it has details.errors instead. That is the one place the two shapes differ, and it is why reason must always be read defensively.

The most common cause by a distance is phone-number formatting. to must match ^\+?\d+$: digits with an optional leading +, 6 to 20 characters. +919876543210 and 919876543210 both pass. +91 98765 43210, +91-98765-43210, and (+91) 98765 43210 are all rejected here, before anything is sent. Strip separators before you call.

Statuses the contract does not name #

A few failures happen before your request reaches any handler — a wrong method, an oversized body, the wrong content type. These still come back in the envelope, mapped by a simple rule:

• Any 4xx the contract does not name → code: "invalid_argument", original status preserved.
• Any 5xx the contract does not name → code: "internal", original status preserved.

So a POST to a GET-only route returns HTTP 405 with code: "invalid_argument", and the framework's Allow response header is preserved alongside the envelope. Your handler should therefore branch on error.code for behaviour but log the HTTP status too — they do not always match the table above, and when they diverge the status is the more specific fact.

Unhandled exceptions on our side always render as:

{
  "error": {
    "code": "internal",
    "message": "Internal server error.",
    "details": {},
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}

The message is deliberately opaque — the real exception is logged on our side only, because stack traces in an API response are a disclosure risk. This is the case where request_id earns its keep: send it to support and the underlying error is one lookup away.

The complete details.reason catalogue #

Grouped by where they come from. Every reason below is a stable string you can branch on.

Authentication — unauthenticated / 401 #

Full detail in Authentication.

Scope and standing: permission_denied / 403 #

See Scopes and Authentication.

Rate limiting: rate_limited / 429 #

All three are 429, and they need different responses: one waits for the next minute, one waits for a call to end, and one waits for tomorrow. See Rate limits.

Idempotency and versions: conflict / 409 #

A stale expected_version on PATCH /tickets/{ticket_id} is also a 409 conflict, but it carries no reason: only expected_version and current_version, with the message "Ticket changed since it was loaded."

See Idempotency.

Contacts — conflict / 409 #

The API refuses to guess which one you meant, and refuses to merge them silently. Message: "Those details belong to two different contacts." Resolve the duplicate in the console, or send one identifier rather than two.

Messages #

template_not_found catches two different mistakes: a genuine typo, and a template that exists but is not yet approved. Both look identical from here. Check the approval state in the console before you assume it is a spelling problem. Templates covers the lifecycle.

When WhatsApp itself refuses a send, the response is 502 provider_error with no reason. details carries WhatsApp's own provider_code, provider_subcode, provider_message, and provider_user_message, and message starts with "WhatsApp rejected this:".

Calls #

agent_number_mismatch is worth understanding rather than working around. The agent that speaks on an outbound call is resolved from the caller-ID number, not from agent_id — agent_id is an assertion, and this error is that assertion failing. details.deployed_agent_id tells you what is actually deployed there. See Outbound calls.

Campaigns #

A campaign started over the API passes the same guardrails as one started in the console. When one refuses, the response is 412 failed_precondition with details.reason, a link to the page that explains it in details.docs, and, for guardrail findings, details.fix and the full details.findings list. The reasons you will meet most:

Every guardrail reason, what it means, and how to fix it is listed in Sending rules. Branch on reason and log docs: it is the same page the console links from a blocked launch.

Duesly #

See Duesly (payments).

Errors that carry no reason #

These come back with details: {} and rely on code plus message:

The not_found cases are worth a note: an id belonging to another workspace returns exactly the same 404 as an id that does not exist. That is an intentional guard — the API will not confirm the existence of a resource you cannot see. If you are certain an id is real and still getting 404, check which workspace's key you are holding.

How to handle errors well #

1. Branch on code, then on reason #

code decides the shape of your response — retry, alert, give up, surface to a user. reason decides the message you write into your own log or your own UI. Never parse message, and never branch on the HTTP status alone: originate_failed is a 500 that means "the call did not go through", which is a different thing from a generic server error even though the status matches.

2. Log request_id on every failure #

Log it structurally, next to your own trace id, on every non-2xx. It is the only identifier that lets us find your exact request. Send X-Correlation-Id on the way in and error.correlation_id will echo it, so one grep spans both systems.

3. Know what is retryable #

4. Fail loudly on 412 #

failed_precondition almost always means a configuration or billing gap: no sender connected, no phone number, no agent deployed to the number, the month's allowance used up. These are not transient and they are not your code's fault. Route them to an alert with the reason attached rather than into a retry queue where they will churn silently until someone notices no messages went out today.

5. A handler you can copy #

const RETRYABLE_CODES = new Set(["rate_limited", "internal", "provider_error"]);

class AmomicError extends Error {
  constructor(status, error) {
    super(`${error.code}: ${error.message}`);
    this.status = status;
    this.code = error.code;
    this.reason = error.details?.reason ?? null;
    this.details = error.details ?? {};
    this.requestId = error.request_id;
    this.correlationId = error.correlation_id;
    this.retryable = RETRYABLE_CODES.has(error.code);
  }
}

async function amomicRequest(path, options = {}, attempt = 1) {
  const response = await fetch(`https://services.amomic.in/api/v1${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  if (response.ok) return response.json();

  const body = await response.json();
  const err = new AmomicError(response.status, body.error);

  console.error("amomic_api_error", {
    status: err.status,
    code: err.code,
    reason: err.reason,
    request_id: err.requestId,
    correlation_id: err.correlationId,
    path,
  });

  // Configuration problems need a human, not a retry.
  if (err.code === "failed_precondition" || err.code === "permission_denied") {
    await alertOps(err);
    throw err;
  }

  // The daily call limit resets tomorrow, not in a few seconds.
  if (err.reason === "daily_call_budget") throw err;

  if ((err.retryable || err.reason === "idempotency_in_progress") && attempt < 4) {
    // The per-key limit resets on the minute boundary; everything else backs off.
    const waitMs =
      err.reason === "rate_limited"
        ? (60 - new Date().getSeconds()) * 1000 + 250
        : err.reason === "idempotency_in_progress"
          ? (err.details.retry_after_seconds ?? 2) * 1000
          : 500 * 2 ** (attempt - 1);
    await new Promise((r) => setTimeout(r, waitMs));
    return amomicRequest(path, options, attempt + 1);
  }

  throw err;
}

Both examples send Idempotency-Key only if you pass one — on any POST, you should. Add X-Correlation-Id from your own tracing context and the two systems' logs join on one value.

Next #