Errors

Every error returned by the Xobito API follows a consistent shape. Use the HTTP status for classification and the message (and optional errors) for detail.

Error envelope

{
  "status": "error",
  "message": "Human-readable description",
  "errors": { "field_name": ["error 1", "error 2"] }
}

Field	Always present	Meaning
`status`	Yes (except 429)	Always `"error"` on failures.
`message`	Yes	A short human-readable description.
`errors`	Only on validation errors	Field-by-field validation messages (object or string).

429 rate-limit responses use a different shape — see Rate Limits.

HTTP statuses

400 Bad Request

Returned when the subdomain path segment is invalid.

{
  "status": "error",
  "message": "Validation failed",
  "errors": "Invalid tenant subdomain"
}

401 Unauthorized

The token is missing or not recognised. Missing header:

{
  "status": "error",
  "message": "API token is required"
}

Invalid / revoked / expired token:

{
  "status": "error",
  "message": "Invalid API token"
}

403 Forbidden

Missing ability (scope):

{
  "status": "error",
  "message": "Token does not have the required ability: contacts.create"
}

The ability name in the message matches exactly the scope the endpoint requires. Plan limit exceeded (e.g. max contacts for the workspace plan):

{
  "status": "error",
  "message": "Contact limit exceeded for your current plan. Upgrade to add more contacts."
}

404 Not Found

The resource does not exist (or does not belong to your workspace).

{
  "status": "error",
  "message": "Contact not found"
}

The resource name in the message varies by endpoint (Contact not found, Status not found, Template not found, etc.).

422 Unprocessable Entity

Validation failed. The errors object maps field names to an array of human-readable messages.

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "phone": ["The phone field is required."],
    "email": ["The email has already been taken."]
  }
}

429 Too Many Requests

Rate limit exceeded. See Rate Limits.

{
  "message": "Too many requests",
  "retry_after": 45
}

500 Internal Server Error

Something broke on Xobito’s side. The message describes the failed action.

{
  "status": "error",
  "message": "Failed to create contact"
}

Retry after a short delay. If the error persists, contact support.

Handling errors

const res = await fetch(url, { headers });
if (!res.ok) {
  const body = await res.json();
  if (res.status === 422) {
    console.error("Validation failed:", body.errors);
  } else if (res.status === 429) {
    await new Promise((r) => setTimeout(r, (body.retry_after || 1) * 1000));
  } else {
    throw new Error(`${res.status}: ${body.message}`);
  }
}

r = requests.get(url, headers=headers)
if not r.ok:
    body = r.json()
    if r.status_code == 422:
        print("Validation failed:", body["errors"])
    elif r.status_code == 429:
        time.sleep(body.get("retry_after", 1))
    else:
        raise RuntimeError(f"{r.status_code}: {body['message']}")

Common mistakes

401 'API token is required'

The Authorization header was missing. It must be exactly Authorization: Bearer <your_token> (64-character hex string, no prefix).

403 with ability name

Your token is valid but lacks the specific ability. Regenerate a new token in Settings → API Management with the ability the endpoint requires.

400 'Invalid tenant subdomain'

The {subdomain} in the URL path does not match any workspace. Check the path: https://dash.xobito.com/api/v1/{subdomain}/....

422 on send-template

Either the template does not exist, does not belong to your workspace, or is not yet APPROVED by Meta. Only APPROVED templates can be sent.

Introduction

API Reference

Webhooks

Data Types

Error envelope

HTTP statuses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Handling errors

Common mistakes

​Error envelope

​HTTP statuses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

​429 Too Many Requests

​500 Internal Server Error

​Handling errors

​Common mistakes

Error envelope

HTTP statuses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Handling errors

Common mistakes