HTTP Status Codes

The Audian API uses standard HTTP status codes to indicate the success or failure of requests.

2xx Success Codes

200 OK

The request was successful and the response contains the requested data.

{
  "success": true,
  "data": {
    "id": "num_abc123",
    "number": "+14155551234"
  }
}

201 Created

The request was successful and a new resource was created.

{
  "success": true,
  "data": {
    "id": "num_abc123",
    "number": "+14155551234",
    "status": "active"
  }
}

202 Accepted

The request was accepted for processing, but the operation is not complete.

{
  "success": true,
  "data": {
    "id": "port_abc123",
    "status": "pending",
    "createdAt": "2024-01-01T12:00:00Z"
  }
}

4xx Client Error Codes

400 Bad Request

The request is malformed or contains invalid parameters.

Common Causes:

• Missing required parameters
• Invalid parameter format
• Invalid JSON in request body
• Invalid query parameters

Example:

{
  "error": {
    "code": "invalid_request_error",
    "message": "The phone_number parameter is invalid",
    "param": "phone_number",
    "type": "invalid_request_error"
  }
}

401 Unauthorized

Authentication failed or is missing.

Common Causes:

• Missing API key
• Invalid API key
• Expired API key
• Incorrect authorization header format

Example:

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

Resolution:

1. Verify your API key is included in the Authorization header
2. Use the format: X-Auth-Token: YOUR_API_KEY
3. Check that your API key is valid in the Audian Dashboard
4. Regenerate the API key if it has been compromised

402 Payment Required

Your account does not have sufficient funds or credit.

Common Causes:

• Insufficient account balance
• Credit card declined
• Subscription expired

Example:

{
  "error": {
    "code": "insufficient_funds",
    "message": "Your account does not have sufficient funds for this operation",
    "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

403 Forbidden

You do not have permission to access this resource.

Common Causes:

• Insufficient permissions
• Account restrictions
• Resource access denied

Example:

{
  "error": {
    "code": "forbidden_error",
    "message": "You do not have permission to access this resource",
    "type": "forbidden_error"
  }
}

404 Not Found

The requested resource does not exist.

Common Causes:

• Invalid resource ID
• Resource has been deleted
• Resource belongs to another account

Example:

{
  "error": {
    "code": "not_found_error",
    "message": "The requested number was not found",
    "type": "not_found_error"
  }
}

Resolution:

1. Verify the resource ID is correct
2. Ensure the resource has not been deleted
3. Check that the resource belongs to your account

409 Conflict

The request conflicts with the current state of the resource.

Common Causes:

• Resource already exists
• Duplicate request
• Invalid state transition

Example:

{
  "error": {
    "code": "conflict_error",
    "message": "The number is already owned by your account",
    "type": "conflict_error"
  }
}

422 Unprocessable Entity

The request contains valid syntax but cannot be processed.

Common Causes:

• Semantic errors in the request
• Business logic validation failure
• Invalid resource state

Example:

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

429 Too Many Requests

Rate limit exceeded.

Common Causes:

• Too many requests in a short time
• Exceeding API quota

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 in your retry logic
3. Consider caching responses to reduce request volume
4. Contact Audian support to increase your rate limit quota

5xx Server Error Codes

500 Internal Server Error

An unexpected error occurred on the server.

Common Causes:

• Server-side bug
• Temporary service disruption
• Database error

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 for service updates
4. Contact Audian support if the error persists

502 Bad Gateway

The server received an invalid response from an upstream service.

Common Causes:

• Upstream service failure
• Network connectivity issue
• Service misconfiguration

Resolution:

1. Retry the request after a few seconds
2. Check the Audian status page
3. Contact Audian support if the error persists

503 Service Unavailable

The server is temporarily unable to handle requests.

Common Causes:

• Server maintenance
• Service overload
• Temporary service outage

Example:

{
  "error": {
    "code": "service_unavailable_error",
    "message": "The service is temporarily unavailable",
    "type": "server_error"
  }
}

Resolution:

1. Retry the request after a few seconds
2. Check the Audian status page for maintenance windows
3. Implement exponential backoff
4. Consider implementing a circuit breaker pattern

Error Handling Best Practices

Implement Proper Error Handling

async function makeRequest() {
  try {
    const response = await client.numbers.search({
      location: 'US-CA-415'
    });
    return response;
  } catch (error) {
    // Handle different status codes
    if (error.status === 401) {
      // Handle authentication error
      refreshApiKey();
    } else if (error.status === 429) {
      // Handle rate limiting
      await wait(error.headers['retry-after'] * 1000);
      return makeRequest();
    } else if (error.status >= 500) {
      // Handle server errors with exponential backoff
      return retryWithBackoff(makeRequest);
    } else {
      // Handle client errors
      throw error;
    }
  }
}

Implement Retry Logic

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      // Don't retry on client errors (4xx)
      if (error.status >= 400 && error.status < 500) {
        throw error;
      }

      if (i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

Monitor Rate Limits

const response = await client.numbers.list();

const rateLimit = {
  limit: response.headers['x-ratelimit-limit'],
  remaining: response.headers['x-ratelimit-remaining'],
  reset: new Date(response.headers['x-ratelimit-reset'] * 1000)
};

console.log(`Rate Limit: ${rateLimit.remaining}/${rateLimit.limit}`);
console.log(`Resets at: ${rateLimit.reset}`);

Status Code Summary

Code	Name	Retryable
200	OK	No
201	Created	No
202	Accepted	No
400	Bad Request	No
401	Unauthorized	No
402	Payment Required	No
403	Forbidden	No
404	Not Found	No
409	Conflict	No
422	Unprocessable Entity	No
429	Too Many Requests	Yes
500	Internal Server Error	Yes
502	Bad Gateway	Yes
503	Service Unavailable	Yes