Errors

Every failure, its status, and what to do about it.

The error shape

Every failure answers with an HTTP status and the same body:

{
  "error": {
    "code": "lead.phone_already_exists",
    "message": "Another lead or contact already has this phone number",
    "requestId": "0b9f6d0e-7c1a-4f4e-9f0a-1d2c3b4a5e6f",
    "details": {
      "existing": { "id": "ent_ba2kccpsr4", "type": "lead" }
    }
  }
}

code: string, required
What failed, for your code to branch on. Codes are part of the contract and are never renamed within v1.
message: string, required
The same, in English, for a person. Do not match on it: it may be reworded.
requestId: string, required
The request's id, also sent as the X-Request-Id header. Include it when you contact support.
details: object
What you can act on, when there is something: the lead that already has the number, the custom fields that were refused, the parts of the request that were invalid.

Statuses

Status	Meaning
`400`	The request is invalid: a missing or malformed field, a body that is not JSON, a stale cursor
`401`	The API key is missing or was not accepted
`404`	The lead does not exist in this workspace, or the endpoint does not exist
`409`	The request conflicts with the workspace's current state
`422`	The request is well formed but cannot be done, such as a number that is not on WhatsApp
`429`	The key made too many requests; wait for `Retry-After`
`500`	Something failed on our side; try again
`503`	WhatsApp could not be reached to check a number; wait for `Retry-After`

Codes

Code	Status	What to do
`request.invalid`	`400` / `404`	Fix the request. The message names the first field at fault; `details.issues` lists every one
`api_key.invalid`	`401`	Check the key. See Authentication
`entity.not_found`	`404`	The lead was deleted, or the `id` belongs to another workspace
`lead.phone_already_exists`	`409`	Use the lead or contact in `details.existing` instead
`lead.changed_concurrently`	`409`	Another request changed the lead at the same moment. Nothing was saved; send it again
`custom_field.invalid_values`	`422`	Fix the values named in `details.fields`
`lead.phone_not_on_whatsapp`	`422`	The number has no WhatsApp account. Check it was typed with its country code
`entity.no_connected_channel`	`422`	Connect a WhatsApp number to the workspace in Swite
`rate_limit.exceeded`	`429`	Wait the seconds in `Retry-After`. See Rate limits
`generic.error`	`500`	Try again. If it keeps failing, contact support with the `requestId`
`lead.whatsapp_unavailable`	`503`	Wait the seconds in `Retry-After`, then try again

New codes may be added within v1. Treat a code you do not know by its status.

Retrying

A 429 or a 503 passes on its own: wait the seconds its Retry-After header gives, then send the request again. A 500 may succeed on a second try. Do not retry any other status unchanged: it fails the same way until the request or the workspace changes.

Retrying a create

A create that timed out may have reached Swite. Sending it again is safe: if the first one went through, the second answers 409 with the lead it created in details.existing.