Errors
When something goes wrong with your API request, the xNumbers API returns an error with a specific status code and error information to help you understand 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.
- Name
401- Description
Unauthorized - Invalid or missing API key.
- Name
403- Description
Forbidden - Valid API key but insufficient permissions.
- Name
404- Description
Not Found - Resource does not exist.
- Name
409- Description
Conflict - Resource conflict (e.g., duplicate user, number already assigned).
- Name
422- Description
Unprocessable Entity - Request validation failed.
- Name
429- Description
Too Many Requests - Rate limit exceeded.
- Name
500- Description
Internal Server Error - Server error.
Error response format
All error responses return a JSON object with an error field containing the error code and message.
Error response
{
"error": {
"code": "invalid_phone_number",
"message": "Phone number format is invalid",
"details": "Phone number must be in E.164 format"
}
}
Error codes
- Name
unauthorized- Description
Invalid or missing API key.
- Name
forbidden- Description
Valid API key but insufficient permissions.
- Name
validation_failed- Description
Request data failed validation.
- Name
resource_not_found- Description
Requested resource does not exist.
- Name
duplicate_resource- Description
Resource already exists (e.g., user email, username).
- Name
number_not_available- Description
Virtual number is not available for assignment.
- Name
number_already_assigned- Description
Virtual number is already assigned to another user.
- Name
insufficient_inventory- Description
No available numbers in requested area.
- Name
invalid_phone_number- Description
Phone number format is invalid (must be E.164 format).
- Name
invalid_role- Description
Specified role does not exist.
- Name
user_limit_exceeded- Description
Account has reached maximum user limit.
- Name
invalid_document- Description
KYC document is invalid or unreadable.
- Name
document_expired- Description
KYC document has expired.
- Name
file_too_large- Description
Uploaded file exceeds size limit.
- Name
rate_limit_exceeded- Description
Too many requests within time window.