Technical reference

Errors: HTTP status codes and JSON payloads

Page updated: 2026-04-03

Summary

Errors combine HTTP status, optional JSON body with a code and message, and (for throttling) Retry-After.

Canonical reference: Hostnames, path prefixes, JSON field names, and changelog are maintained on docs.waping.app. Examples below are illustrative — align your integration with the live OpenAPI/reference there.

Purpose

Standardize troubleshooting for integrations, queues, and automation flows.

Best for

Log full response bodies on failure for support tickets.
Classify errors before retrying—do not blanket-retry 4xx except 429/5xx per policy.

Not for

Treating SESSION_DISCONNECTED as an auth problem—usually requires operator action on the phone.
Assuming error code strings never change—handle unknown codes safely.

Response shape (example)

JSON error envelope (illustrative)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Error table

HTTP	Code (example)	Meaning	Retry?
400	VALIDATION_ERROR	Malformed JSON or invalid field values.	No — fix request.
401	UNAUTHORIZED	Invalid or missing API key.	No — fix credentials.
403	FORBIDDEN	Key valid but plan or scope disallows action.	No — upgrade or scope.
404	NOT_FOUND	Resource ID unknown in workspace.	No — fix ID.
409	IDEMPOTENCY_CONFLICT	Idempotency-Key reused with different body.	No — use new key or same body.
429	RATE_LIMITED	Throttled — see Retry-After.	Yes — backoff.
4xx	SESSION_DISCONNECTED	QR session not connected for device.	Retry after reconnect — see QR lifecycle.
5xx	SERVER_ERROR	Transient upstream or WAPing failure.	Yes — limited backoff.

Payload examples

409 Conflict (idempotency)

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Idempotency-Key reused with different body"
  }
}

4xx session

{
  "error": {
    "code": "SESSION_DISCONNECTED",
    "message": "WhatsApp session is not connected"
  }
}

Workflow

Log correlation IDs (request id, message id, event id) when present.
Retry 429 and 5xx with exponential backoff; cap attempts.
Do not retry 400/401/403/404/409 unless the underlying cause is fixed.

Limits

Error rate from repeated bad requests may trigger additional throttling or account review — fix root cause promptly.

Caveats

Exact code enumerations may evolve — consume unknown codes safely and log raw payloads.