Errors

When something goes wrong with your API request, the xNumbers API returns an error with a specific status code and a JSON body describing what happened.

Status codes

Name
200
Description
OK - Request successful.
Name
201
Description
Created - Resource created successfully.
Name
400
Description
Bad Request - Invalid request parameters or failed validation.
Name
401
Description
Unauthorized - Missing or invalid API key or token.
Name
403
Description
Forbidden - Valid credentials but insufficient permissions, or an attempt to access another customer's data.
Name
404
Description
Not Found - Resource does not exist.
Name
409
Description
Conflict - Resource conflict (e.g., duplicate resource, invalid state transition).
Name
500
Description
Internal Server Error - Unexpected server error.

Error responses are JSON objects with a statusCode, a message, and (in most cases) an error field naming the HTTP error. The message field contains a human-readable description of what went wrong.

Error response

{
  "statusCode": 404,
  "message": "Number not found",
  "error": "Not Found"
}

Validation errors

When request validation fails (status 400), the message field is an array of strings - one entry per failed constraint - so you can surface every problem with the request at once.

Validation error response

{
  "statusCode": 400,
  "message": [
    "page must not be less than 1",
    "limit must not be greater than 100"
  ],
  "error": "Bad Request"
}

Common error examples

401 Unauthorized is returned when the request carries no credentials, an invalid or expired API key, or an invalid token. Check that you're sending Authorization: Bearer xn_... (or X-API-Key: xn_...) and that the key is still active.

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

403 Forbidden is returned when your credentials are valid but the key or user lacks the permission required by the endpoint - for example calling a create/update/delete endpoint with a read-only API key - or when the {customer_slug} in the URL does not match your own customer account.

403 Forbidden

{
  "statusCode": 403,
  "message": "You do not have permission to perform this action",
  "error": "Forbidden"
}

404 Not Found is returned when the resource doesn't exist or doesn't belong to your customer account. The message describes the missing resource.

404 Not Found

{
  "statusCode": 404,
  "message": "Number not found",
  "error": "Not Found"
}

409 Conflict is returned when the request conflicts with the current state of a resource - for example creating something that already exists.

409 Conflict

{
  "statusCode": 409,
  "message": "Resource already exists",
  "error": "Conflict"
}

500 Internal Server Error indicates an unexpected failure on our side. These are safe to retry; if the error persists, contact support with the request details.

500 Internal Server Error

{
  "statusCode": 500,
  "message": "Internal server error"
}