Errors

Failures always come back in the same shape, whatever went wrong:

{
  "success": false,
  "error": {
    "code": "outside_24h_window",
    "message": "…"
  },
  "request_id": "8f1c2b74-…"
}

Field	What it’s for
`error.code`	A short, stable identifier. This is what your code should branch on.
`error.message`	Human-readable explanation. Useful in logs; never match on it.
`error.details`	Present on some errors with structured extras — for example the daily quota error carries `limit` and `resetAt`.
`request_id`	Identifies this exact request. Also returned as the `X-Request-Id` response header.

Log request_id alongside every failure you record. It’s the fastest way to have a specific call looked up if you need help with one.

You can also set your own X-Request-Id on a request and Paige will use it, which makes tracing across your system and Paige’s much easier.

Status codes

Status	Meaning	Do this
`400`	Bad request — validation failed, or something in the request doesn’t make sense.	Fix the request. Retrying unchanged won’t help.
`401`	Missing, malformed, revoked, or expired credential.	Check the `Authorization` header. See Authentication.
`402`	Out of credits.	Top up credits for the project.
`403`	Authenticated, but not allowed.	Usually a missing scope or a paused project. See Scopes.
`404`	No such resource.	Check the id or name.
`409`	Conflict with current state.	Depends on the code — see below.
`410`	The resource existed but is gone for good.	Media at Meta expires; re-fetch from the source.
`429`	Throttled, or the daily send allowance is used up.	Honour `Retry-After`. See Rate limits.
`500`	Something broke on Paige’s side.	Safe to retry with backoff.
`502`	Meta (WhatsApp) rejected the upstream call.	Read the message — it carries Meta’s own detail.

Common error codes

Request problems (400)

Code	What happened
`bad_request`	Generic validation failure.
`invalid_request`	The request body didn’t match the endpoint’s schema.
`invalid_json`	The body isn’t valid JSON.
`invalid_id`	An identifier in the path or body isn’t a well-formed id.
`invalid_cursor`	The paging cursor you passed isn’t one Paige issued.
`invalid_idempotency_key`	The `Idempotency-Key` header is empty or longer than 255 characters.
`invalid_project_header`	`X-Paige-Project` was sent but blank.
`project_required`	A multi-project connection tried a write without naming a project.

Message sends add their own validation codes — invalid_phone, missing_recipient, missing_template_name, missing_language, template_variable_mismatch, unsupported_message_type, too_many_buttons, and others. Each names precisely what to fix.

Credential problems (401 / 403)

Code	Status
`api_key_required`	401
`invalid_api_key`	401
`invalid_token`	401
`insufficient_scope`	403
`project_inactive`	403
`project_not_attached`	403
`no_project_access`	403
`protected_file`	403

All of these are covered in Authentication. protected_file is separate: it means a write targeted a file the platform manages, which your integration isn’t allowed to edit.

Conflicts (409)

Code	What happened
`outside_24h_window`	You tried to send a free-form message to someone who hasn’t messaged you in the last 24 hours. Send an approved template instead.
`template_exists`	A template with that name and language already exists.
`idempotency_in_progress`	The same `Idempotency-Key` is still being processed. Retry shortly.
`idempotency_key_mismatch`	That key was already used with a different request body.

The last two are explained in Idempotency.

outside_24h_window is the single most common surprise for new integrations. WhatsApp only lets you send free-form messages inside a 24-hour window that opens when the customer messages you. Outside it, an approved template is the only thing that goes through. See Templates.

Too many requests (429)

Code	What happened
`rate_limited`	Too many API requests. Back off and retry.
`quota_exceeded`	The project’s daily WhatsApp send allowance is used up.

Both carry Retry-After. They’re genuinely different problems — see Rate limits.

Upstream and server (5xx)

Code	Status	What happened
`meta_auth_error`	502	Meta rejected the project’s WhatsApp credentials. Reconnect WhatsApp under Settings → WhatsApp.
`build_failed`	502	The code agent couldn’t complete the build.
`flow_generation_failed`	502	The flows agent couldn’t build the flow. Try a more specific instruction.
`flow_update_failed`	502	The flows agent couldn’t apply the change to an existing flow.
`server_error`	500	An unexpected error on Paige’s side.

You’ll also see some codes in SCREAMING_SNAKE_CASE — PROJECT_NOT_FOUND, SEGMENT_NOT_FOUND, MEDIA_EXPIRED, BROADCAST_NOT_FOUND and similar. They come from the shared capability layer that the AI agent tools use too, and they behave exactly like any other code. Match on them the same way.

Retrying

Status	Retry?
`400`, `401`, `403`, `404`, `409`	No — the request itself needs changing.
`429`	Yes, after `Retry-After` seconds.
`500`, `502`	Yes, with exponential backoff.

Before you retry a POST /v1/messages that timed out or 5xx’d, read Idempotency. Without an Idempotency-Key, a retry can send the same WhatsApp message to a customer twice.

Getting started

Endpoints

Status codes

Common error codes

Request problems (400)

Credential problems (401 / 403)

Conflicts (409)

Too many requests (429)

Upstream and server (5xx)

Retrying

​Status codes

​Common error codes

​Request problems (400)

​Credential problems (401 / 403)

​Conflicts (409)

​Too many requests (429)

​Upstream and server (5xx)

​Retrying

Status codes

Common error codes

Request problems (400)

Credential problems (401 / 403)

Conflicts (409)

Too many requests (429)

Upstream and server (5xx)

Retrying