Errors

Error format

When a request fails, the API returns an error object with three fields:

{
  "statusCode": 400,
  "message": "Validation failed: phone_number must be in E.164 format",
  "error": "Bad Request"
}

Field	Type	Description
`statusCode`	integer	The HTTP status code.
`message`	string or array	A human-readable description of the error. Validation errors may return an array of messages, one per invalid field.
`error`	string	The short HTTP status name (e.g., `"Bad Request"`, `"Not Found"`).

Validation error example

When multiple fields fail validation, message is an array:

{
  "statusCode": 400,
  "message": [
    "phone_number must be in E.164 format",
    "agent_id should not be empty"
  ],
  "error": "Bad Request"
}

HTTP status codes

Code	Name	When it occurs
`200`	OK	The request succeeded. Returned for GET, PATCH, and DELETE operations.
`201`	Created	A new resource was created successfully. Returned for POST operations.
`400`	Bad Request	The request body or query parameters failed validation.
`401`	Unauthorized	Missing or invalid API key.
`403`	Forbidden	Your API key does not have permission, or the requested destination is blocked by workspace Telephony Config.
`404`	Not Found	The requested resource does not exist, or does not belong to your organization.
`409`	Conflict	The operation conflicts with the current state, for example registering a phone number that already exists.
`422`	Unprocessable Entity	Some platform services may use this for semantic validation. Only depend on it when the endpoint contract lists a `422` response.
`429`	Too Many Requests	A gateway or service rate limit was reached. Retry with backoff; honor `Retry-After` only when that header is present.
`500`	Internal Server Error	An unexpected error occurred on our side. If this persists, contact support.

Handling errors in code

TypeScript / JavaScript

async function createCall(apiKey: string, agentId: string, phoneNumber: string) {
  const response = await fetch("https://api.dialnexa.com/v1/calls", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: agentId,
      phone_number: phoneNumber,
      metadata: {},
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(
      `API error ${error.statusCode}: ${
        Array.isArray(error.message) ? error.message.join(", ") : error.message
      }`
    );
  }

  return response.json();
}

Python

import requests

def create_call(api_key: str, agent_id: str, phone_number: str) -> dict:
    response = requests.post(
        "https://api.dialnexa.com/v1/calls",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={
            "agent_id": agent_id,
            "phone_number": phone_number,
            "metadata": {},
        },
    )

    if not response.ok:
        error = response.json()
        msg = error.get("message", "Unknown error")
        if isinstance(msg, list):
            msg = ", ".join(msg)
        raise Exception(f"API error {error.get('statusCode')}: {msg}")

    return response.json()

Common mistakes

401 Unauthorized - Your API key is missing, malformed, or has been revoked. Check that you are passing Authorization: Bearer YOUR_API_KEY and that the key has not expired. 400 Bad Request on phone numbers - Phone numbers must be in E.164 format: + followed by the country code and number, with no spaces or dashes. For example, +919876543210 not 9876543210. 403 Forbidden on outbound destinations - The destination number is valid, but the route is not enabled for your workspace. Check Workspace Settings > Telephony Config for the destination country and network-group prefix, or use an enabled SIP/BYOC route. 404 Not Found - The resource ID is correct but the resource belongs to a different organization. All resources are scoped to the organization associated with your API key. 409 Conflict - You are trying to perform an action that is not valid for the current state of the resource. For example, registering a phone number that already exists or applying a status action that the resource cannot accept.

Retry decision table

Situation	Retry?	Recommended action
Network timeout before any response	Maybe	Check whether the operation has side effects before retrying. For create or call operations, first look for the resource by your own correlation data.
`400`, `401`, `403`, `404`, or `409`	No	Fix the request, credentials, permissions, resource ID, or resource state.
`429`	Yes	Use exponential backoff with jitter. Honor `Retry-After` when the response includes it.
`500`, `502`, `503`, or `504` on a read	Yes	Retry with capped exponential backoff.
`500`, `502`, `503`, or `504` on a write	Maybe	Retry only when the endpoint page marks the action retry safe or you can confirm the first attempt did not take effect.

See Reliability and retries for production-safe retry patterns and current platform guarantees.

Overview

Endpoints - v1

Endpoints - Legacy

Code Examples And SDK Status

Error format

Validation error example

HTTP status codes

Handling errors in code

TypeScript / JavaScript

Python

Common mistakes

Retry decision table

​Error format

​Validation error example

​HTTP status codes

​Handling errors in code

​TypeScript / JavaScript

​Python

​Common mistakes

​Retry decision table

Error format

Validation error example

HTTP status codes

Handling errors in code

TypeScript / JavaScript

Python

Common mistakes

Retry decision table