Errors

Standard error format and error codes returned by the DialNexa API.

Error format

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

{
  "statusCode": 400,
  "message": "Validation failed: to_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": [
    "to_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.
304	Not Modified	Returned for conditional GET requests when the ETag matches and data has not changed.
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 (e.g., trying to resume a cancelled campaign).
422	Unprocessable Entity	The request was well-formed but contained semantic errors (e.g., an agent assigned to a deleted phone number).
429	Too Many Requests	You have exceeded the rate limit. See Rate Limits.
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,
      to_phone_number: phoneNumber,
    }),
  });

  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,
            "to_phone_number": phone_number,
        },
    )

    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, [phone] 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, trying to resume a campaign that has been cancelled, or deleting an agent that is still assigned to an active campaign.