Skip to main content
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"] }
}
FieldAlways presentMeaning
statusYes (except 429)Always "error" on failures.
messageYesA short human-readable description.
errorsOnly on validation errorsField-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}`);
  }
}

​
Common mistakes

The Authorization header was missing. It must be exactly Authorization: Bearer apitk_....
Your token is valid but lacks the specific ability. Regenerate a new token in Settings → API Management with the ability the endpoint requires.
The {subdomain} in the URL path does not match any workspace. Check the path: https://dash.xobito.com/api/v1/{subdomain}/....
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.