Errors and Status Codes

The standard WUTS error envelope, HTTP status codes, and the stable error_code catalog returned across the API.

When a request fails, WUTS returns a consistent JSON error envelope alongside an HTTP status code. Your integration should branch on the machine-readable error_code and the HTTP status — never on the human-readable error string, which may be reworded over time.

The error envelope

Every error response shares the same shape:

{
  "success": false,
  "error": "WhatsApp session is not connected",
  "error_code": "DEVICE_NOT_READY",
  "timestamp": "2026-06-15T13:45:02Z",
  "validation": [
    {
      "field": "text",
      "message": "text is required and must be between 1 and 4096 characters",
      "value": ""
    }
  ]
}

Field	Type	Notes
`success`	boolean	Always `false` on error. Successful responses use `true`.
`error`	string	Human-readable message. For display/logging only — do not match on it.
`error_code`	string	Stable, uppercase machine code. Branch your logic on this.
`timestamp`	string	RFC 3339 / ISO 8601 UTC instant the error was produced.
`validation`	array	Present only for field-level validation failures. Omitted otherwise.

Each entry in validation carries the offending field, a message explaining the constraint, and the rejected value.

Successful responses do not use this envelope. They return success: true plus the operation payload (for example message_id, status, chat_jid on a send). See Conventions for the success shape.

HTTP status codes

Status	Meaning	When WUTS returns it
`200 OK`	Success	Request processed; payload returned (e.g. message sent or deleted).
`201 Created`	Created	A new resource was created (e.g. a pairing/connection initiated).
`400 Bad Request`	Client error	Malformed JSON, missing required fields, invalid JID, or failed validation.
`401 Unauthorized`	Auth error	Missing or invalid `Authorization: Bearer <token>`. See Authentication.
`403 Forbidden`	Auth error	Token is valid but not permitted for the target resource.
`404 Not Found`	Not found	Unknown route, device not found, or message not found / already deleted.
`409 Conflict`	Conflict	The request conflicts with current state (e.g. duplicate or already-applied action).
`500 Internal Server Error`	Server error	Unexpected failure acquiring the device or sending the message.
`502 Bad Gateway`	Gateway error	An upstream WhatsApp operation failed (e.g. disconnect or history sync).
`503 Service Unavailable`	Transient	The device is not connected/ready yet; the WhatsApp session is unavailable.

Error code catalog

These are the stable error_code values you will encounter across the API. The error text shown is illustrative.

`error_code`	Typical HTTP	Meaning
`VALIDATION_ERROR`	`400`	One or more fields failed validation. Inspect the `validation` array.
`INVALID_JSON`	`400`	Request body is not valid JSON or does not match the expected schema.
`INVALID_REQUEST_FORMAT`	`400`	The request could not be bound to the expected structure.
`MISSING_REQUIRED_FIELDS`	`400`	A required field (e.g. `messageId`, `chatJid`) was empty.
`INVALID_CHAT_JID`	`400`	The supplied chat JID could not be parsed or resolved.
`DEVICE_NOT_READY`	`503`	The device exists but its WhatsApp session is not connected/logged in yet.
`DEVICE_DISCONNECTED`	`503`	The session was connected but is currently disconnected.
`SERVICE_UNAVAILABLE`	`503`	The WhatsApp service is temporarily unavailable for this device.
`DEVICE_ERROR`	`500`	WUTS failed to acquire the WhatsApp device for the request.
`CLIENT_ERROR`	`500`	The underlying WhatsApp client could not be obtained.
`SEND_FAILED`	`500`	The message reached the gateway but sending to WhatsApp failed.
`SYNC_REQUEST_FAILED`	`502`	A history-sync request to WhatsApp failed upstream.
`MESSAGE_NOT_FOUND`	`404`	The referenced message does not exist or was already deleted.
`DELETE_FAILED`	`500`	The message could not be revoked/deleted.
`DELETE_TIME_EXPIRED`	`400`	The delete-for-everyone time window has elapsed; only local delete remains.

The catalog grows as endpoints are added. Treat an unrecognized error_code the same way you treat its HTTP status: a 4xx is your bug, a 5xx/503 is transient. Always read error_code first and fall back to the status code.

Worked example

A POST /send/text with an empty text fails validation:

curl -X POST https://api.wuts.com.br/send/text \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "number": "5511999999999", "text": "" }'

WUTS replies 400 Bad Request:

{
  "success": false,
  "error": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "timestamp": "2026-06-15T13:45:02Z",
  "validation": [
    {
      "field": "text",
      "message": "text is required and must be between 1 and 4096 characters",
      "value": ""
    }
  ]
}

If instead the device's WhatsApp session is not connected, the same call returns 503 Service Unavailable with no validation array:

{
  "success": false,
  "error": "WhatsApp session is not connected",
  "error_code": "DEVICE_NOT_READY",
  "timestamp": "2026-06-15T13:45:02Z"
}

How to handle errors

Group your handling into two buckets.

4xx — client errors (fix the request)

A 400, 401, 403, 404, or 409 means the request itself is wrong and retrying it unchanged will fail again.

400 / VALIDATION_ERROR / INVALID_JSON / MISSING_REQUIRED_FIELDS: correct the payload — fix the field reported in validation, send valid JSON, or supply the missing required field.
400 / INVALID_CHAT_JID: send a well-formed JID, e.g. a user JID like 5511999999999@s.whatsapp.net or a group JID like 120363039000000000@g.us. See Conventions.
401 / 403: check your Authorization: Bearer <token> header and the token's permissions — see Authentication.
404 / MESSAGE_NOT_FOUND: the target (device or message) does not exist; do not retry.

5xx / 503 — transient states (retry with backoff)

A 500, 502, or 503 reflects a device or gateway condition that is often temporary.

503 / DEVICE_NOT_READY / DEVICE_DISCONNECTED / SERVICE_UNAVAILABLE: the session is connecting or down. Wait for the device to come online, then retry. See Connect a device and watch the connection state via Webhooks.
502 / SYNC_REQUEST_FAILED and 500 / SEND_FAILED / DEVICE_ERROR: retry with exponential backoff.

Retry only idempotent or de-duplicated operations. For sends, reuse the same natural key (or check the resulting message_id) so a retry after a 5xx does not deliver a duplicate. Add jitter to your backoff and cap retries.

Never retry a 4xx without changing the request — it will keep failing and may count against your rate limits.

See also: Quickstart · Conventions · Rate limits · Webhooks.