Errors

The Integration API uses conventional HTTP status codes.

Status	Meaning
200 OK	Request succeeded; body contains the result.
201 Created	Resource created; Location header points to it.
204 No Content	Request succeeded; nothing to return (e.g. delete).
400 Bad Request	The request was invalid. The body describes why.
401 Unauthorized	Missing, expired, or invalid access token — or the token’s audience/issuer is not accepted. Obtain a fresh token and retry once.
403 Forbidden	Token is valid but does not grant access to this resource.
404 Not Found	The resource does not exist (or was already deleted).
429 Too Many Requests	Slow down and honor the Retry-After header if present.
5xx	Server-side problem. Retry with exponential backoff.

Validation error format

Model validation failures return 400 with an errors object keyed by field name:

{
  "errors": {
    "Destination": [
      "The Destination field is required."
    ]
  }
}

Domain validation failures (e.g. an unknown webhook event type) return 400 with a plain descriptive message:

"Unknown event type(s): call.stats. Known event types: agent.status, call.status, interaction.text, interaction.email, interaction.ended."

Handling guidance

• 400 — a bug in your request; do not retry unchanged. Log the body.
• 401 — refresh the token and retry once; if it persists, verify your client credentials and the scope you request (see Authentication).
• 404 on delete — safe to treat as success if your goal is “make sure it’s gone”.
• 5xx/network errors — retry with exponential backoff and jitter; make the operation idempotent on your side where possible.