Error Codes Reference

This page provides a comprehensive reference of all Audian API error codes.

Authentication Errors

invalid_api_key

HTTP Status: 401 Message: The API key provided is invalid or has expired

Cause:

• API key is missing from the request
• API key is malformed
• API key has been revoked
• API key has expired

Example:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid",
    "type": "authentication_error"
  }
}

Resolution:

1. Verify your API key is correctly formatted
2. Check that the API key is active in the Audian Dashboard
3. Regenerate the API key if necessary
4. Ensure the API key is included in the Authorization header

missing_authentication

HTTP Status: 401 Message: Authentication credentials were not provided

Cause:

• Authorization header is missing
• No API key provided

Resolution: Include the API key in the Authorization header:

X-Auth-Token: YOUR_API_KEY

Validation Errors

invalid_request_error

HTTP Status: 400 Message: The request contains invalid parameters or format

Cause:

• Missing required parameters
• Invalid parameter format
• Invalid parameter values
• Malformed JSON request body

Example:

{
  "error": {
    "code": "invalid_request_error",
    "message": "The phone_number parameter must be in E.164 format",
    "param": "phone_number",
    "type": "invalid_request_error"
  }
}

Resolution:

1. Check the endpoint documentation for required parameters
2. Verify parameter formats (e.g., phone numbers must be in E.164 format: +1XXXXXXXXXX)
3. Ensure parameter values are of the correct type
4. Validate JSON syntax in request body

invalid_phone_number

HTTP Status: 400 Message: The phone number is invalid or in an unsupported format

Cause:

• Phone number is not in E.164 format
• Phone number is for an unsupported region
• Phone number contains invalid characters

Example:

{
  "error": {
    "code": "invalid_phone_number",
    "message": "The phone number must be in E.164 format (+1XXXXXXXXXX)",
    "param": "phone_number",
    "type": "invalid_request_error"
  }
}

Resolution: Use E.164 format for all phone numbers:

+1 [area code] [number]
Example: +14155551234

invalid_location

HTTP Status: 400 Message: The location format is invalid

Cause:

• Location code is not in the correct format
• Location is not supported

Example:

{
  "error": {
    "code": "invalid_location",
    "message": "The location must be in format: country-state-areacode",
    "param": "location",
    "type": "invalid_request_error"
  }
}

Valid Formats:

• US-CA-415 (Country-State-Area Code)
• US-NY (Country-State)
• US (Country only)

invalid_parameter

HTTP Status: 400 Message: The parameter value is invalid

Cause:

• Parameter value is outside valid range
• Parameter value is invalid for the operation
• Parameter combination is invalid

Example:

{
  "error": {
    "code": "invalid_parameter",
    "message": "The limit parameter must be between 1 and 100",
    "param": "limit",
    "type": "invalid_request_error"
  }
}

missing_required_parameter

HTTP Status: 400 Message: A required parameter is missing

Cause:

• Required parameter was not included in the request

Example:

{
  "error": {
    "code": "missing_required_parameter",
    "message": "The 'phone_number' parameter is required",
    "param": "phone_number",
    "type": "invalid_request_error"
  }
}

Rate Limiting

rate_limit_error

HTTP Status: 429 Message: Too many requests. Please retry after the specified time

Cause:

• Request rate exceeds API limits
• Monthly quota exceeded

Example:

{
  "error": {
    "code": "rate_limit_error",
    "message": "Too many requests. Please retry after 60 seconds",
    "type": "rate_limit_error"
  }
}

Headers:

Retry-After: 60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067260

Resolution:

1. Wait the duration specified in the Retry-After header
2. Implement exponential backoff
3. Cache responses when possible
4. Contact Audian to increase rate limits

Resource Errors

not_found_error

HTTP Status: 404 Message: The requested resource was not found

Cause:

• Resource ID is invalid
• Resource has been deleted
• Resource belongs to another account

Example:

{
  "error": {
    "code": "not_found_error",
    "message": "The phone number 'num_abc123' was not found",
    "type": "not_found_error"
  }
}

already_exists

HTTP Status: 409 Message: The resource already exists

Cause:

• Resource with the same identifier already exists
• Attempting to create a duplicate resource

Example:

{
  "error": {
    "code": "already_exists",
    "message": "This phone number is already in your account",
    "type": "conflict_error"
  }
}

resource_conflict

HTTP Status: 409 Message: The operation conflicts with the current state of the resource

Cause:

• Invalid state transition
• Concurrent modification
• Conflicting operations

Example:

{
  "error": {
    "code": "resource_conflict",
    "message": "The number is currently being ported and cannot be modified",
    "type": "conflict_error"
  }
}

Business Logic Errors

insufficient_funds

HTTP Status: 402 Message: Your account does not have sufficient funds

Cause:

• Account balance is too low
• Payment method failed
• Subscription expired

Example:

{
  "error": {
    "code": "insufficient_funds",
    "message": "Your account does not have sufficient funds to purchase this number",
    "type": "insufficient_funds_error"
  }
}

Resolution:

1. Add funds to your account via the Audian Dashboard
2. Update your payment method
3. Check your account balance

number_not_available

HTTP Status: 422 Message: The requested phone number is not available

Cause:

• Number has been purchased by another user
• Number is no longer available
• Number is reserved

Example:

{
  "error": {
    "code": "number_not_available",
    "message": "+14155551234 is no longer available",
    "type": "validation_error"
  }
}

Resolution: Search for other available numbers in the same location

cannot_port_number

HTTP Status: 422 Message: The number cannot be ported

Cause:

• Number is not eligible for porting
• Number is from an unsupported carrier
• Account verification incomplete
• Number already pending port

Example:

{
  "error": {
    "code": "cannot_port_number",
    "message": "The number cannot be ported to Audian at this time",
    "type": "validation_error"
  }
}

invalid_routing_configuration

HTTP Status: 422 Message: The routing configuration is invalid

Cause:

• Destination number is invalid
• Call forwarding target is unreachable
• Conference settings are invalid

Example:

{
  "error": {
    "code": "invalid_routing_configuration",
    "message": "The call forward destination must be a valid phone number",
    "param": "forwardTo",
    "type": "validation_error"
  }
}

operation_not_allowed

HTTP Status: 403 Message: This operation is not allowed

Cause:

• Insufficient permissions
• Feature not enabled on account
• Operation not available for this resource

Example:

{
  "error": {
    "code": "operation_not_allowed",
    "message": "MMS is not enabled on your account",
    "type": "forbidden_error"
  }
}

Server Errors

internal_server_error

HTTP Status: 500 Message: An internal server error occurred

Cause:

• Unexpected server-side error
• Database error
• Third-party service failure

Example:

{
  "error": {
    "code": "internal_server_error",
    "message": "An internal server error occurred",
    "type": "server_error"
  }
}

Resolution:

1. Retry the request after a few seconds
2. Implement exponential backoff
3. Check the Audian status page
4. Contact Audian support if issue persists

service_unavailable_error

HTTP Status: 503 Message: The service is temporarily unavailable

Cause:

• Server maintenance
• Service overload
• Temporary outage

Example:

{
  "error": {
    "code": "service_unavailable_error",
    "message": "The service is temporarily unavailable. Please try again later.",
    "type": "server_error"
  }
}

Resolution:

1. Retry after a brief delay
2. Check the Audian status page
3. Implement exponential backoff

Error Code Summary

Code	HTTP Status	Type	Retryable
invalid_api_key	401	authentication_error	No
missing_authentication	401	authentication_error	No
invalid_request_error	400	invalid_request_error	No
invalid_phone_number	400	invalid_request_error	No
invalid_location	400	invalid_request_error	No
invalid_parameter	400	invalid_request_error	No
missing_required_parameter	400	invalid_request_error	No
rate_limit_error	429	rate_limit_error	Yes
not_found_error	404	not_found_error	No
already_exists	409	conflict_error	No
resource_conflict	409	conflict_error	No
insufficient_funds	402	insufficient_funds_error	No
number_not_available	422	validation_error	No
cannot_port_number	422	validation_error	No
invalid_routing_configuration	422	validation_error	No
operation_not_allowed	403	forbidden_error	No
internal_server_error	500	server_error	Yes
service_unavailable_error	503	server_error	Yes