API Reference

Error Codes

Understand API errors and how to resolve them.

Error Response Format

When an error occurs, the API returns a JSON response with details about what went wrong:

json

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": {
      "name": ["Name is required"],
      "instructions": ["Instructions must be at least 10 characters"]
    }
  }
}

Request ID

Every API response includes a unique request ID in the X-Request-Id header. Include this ID when contacting support to help us quickly identify and resolve issues.

http

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Request-Id: req_1a2b3c4d5e6f7g8h
 
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid request body"
  }
}

💡 Pro tip: Log the X-Request-Id header in your application to make debugging easier. Include it in your error tracking system (Sentry, Datadog, etc.).

HTTP Status Codes

Status	Description
200	OK — Request succeeded
201	Created — Resource created successfully
400	Bad Request — Invalid parameters or request body
401	Unauthorized — Invalid or missing API key
403	Forbidden — Insufficient permissions
404	Not Found — Resource doesn't exist
409	Conflict — Resource already exists (e.g., duplicate phone)
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error — Something went wrong on our end

Error Codes

Code	HTTP	Description	Resolution
unauthorized	401	Missing Authorization header	Include `Authorization: Bearer YOUR_API_KEY`
invalid_api_key	401	API key is invalid or revoked	Generate a new API key in Settings
validation_error	400	Request parameters are invalid	Check `details` for field-specific errors
not_found	404	Resource not found	Verify the resource ID exists
rate_limited	429	Too many requests	Wait and retry with exponential backoff
CONFLICT	409	Resource conflict (e.g., duplicate)	Check for existing resources
internal_error	500	Internal server error	Retry or contact support

Common Errors & Solutions

“Invalid or missing API key”

The API key in your request is incorrect or has been revoked.

Solutions:

Verify you're using the correct API key
Ensure the key hasn't been revoked
Check for typos or extra whitespace
Generate a new key if needed

“Too many requests”

You've exceeded the rate limit for API requests.

Solutions:

Check X-RateLimit-Reset header for when to retry
Implement exponential backoff
Reduce request frequency
Cache responses when possible

“Invalid request body”

The request body contains invalid or missing fields.

Solutions:

Check the details field for specific errors
Verify all required fields are included
Ensure data types match (string, number, etc.)
Check for JSON syntax errors

“Resource not found”

The requested resource doesn't exist or has been deleted.

Solutions:

Verify the resource ID is correct
Check if the resource was deleted
Ensure you have access to this workspace
List resources to find the correct ID

Error Handling Best Practices

error-handling.js

async function makeApiRequest(endpoint, options = {}) {
  const response = await fetch(`https://www.nutalk.ai/v1${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${process.env.NUTALK_API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
 
  const data = await response.json();
 
  if (!data.success) {
    const error = data.error;
 
    switch (error.code) {
      case 'rate_limited':
        // Wait and retry
        const resetTime = response.headers.get('X-RateLimit-Reset');
        const waitMs = (parseInt(resetTime) - Date.now()) + 1000;
        await sleep(waitMs);
        return makeApiRequest(endpoint, options);
 
      case 'validation_error':
        // Log validation details for debugging
        console.error('Validation errors:', error.details);
        throw new ValidationError(error.message, error.details);
 
      case 'unauthorized':
      case 'invalid_api_key':
        // Don't retry auth errors
        throw new AuthenticationError(error.message);
 
      case 'internal_error':
        // Retry with exponential backoff
        if (options.retries < 3) {
          await sleep(Math.pow(2, options.retries) * 1000);
          return makeApiRequest(endpoint, {
            ...options,
            retries: (options.retries || 0) + 1
          });
        }
        throw new ServerError(error.message);
 
      default:
        throw new ApiError(error.code, error.message);
    }
  }
 
  return data;
}

Need Help?

If you encounter persistent errors, contact our support team at support@nutalk.ai with your request ID and error details.

AnteriorWebhooks SiguienteRate Limits

Error Response Format

When an error occurs, the API returns a JSON response with details about what went wrong:

json

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": {
      "name": ["Name is required"],
      "instructions": ["Instructions must be at least 10 characters"]
    }
  }
}

Request ID

Every API response includes a unique request ID in the X-Request-Id header. Include this ID when contacting support to help us quickly identify and resolve issues.

http

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Request-Id: req_1a2b3c4d5e6f7g8h
 
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid request body"
  }
}

💡 Pro tip: Log the X-Request-Id header in your application to make debugging easier. Include it in your error tracking system (Sentry, Datadog, etc.).

HTTP Status Codes

Status	Description
200	OK — Request succeeded
201	Created — Resource created successfully
400	Bad Request — Invalid parameters or request body
401	Unauthorized — Invalid or missing API key
403	Forbidden — Insufficient permissions
404	Not Found — Resource doesn't exist
409	Conflict — Resource already exists (e.g., duplicate phone)
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error — Something went wrong on our end

Error Codes

Code	HTTP	Description	Resolution
unauthorized	401	Missing Authorization header	Include `Authorization: Bearer YOUR_API_KEY`
invalid_api_key	401	API key is invalid or revoked	Generate a new API key in Settings
validation_error	400	Request parameters are invalid	Check `details` for field-specific errors
not_found	404	Resource not found	Verify the resource ID exists
rate_limited	429	Too many requests	Wait and retry with exponential backoff
CONFLICT	409	Resource conflict (e.g., duplicate)	Check for existing resources
internal_error	500	Internal server error	Retry or contact support

Common Errors & Solutions

“Invalid or missing API key”

The API key in your request is incorrect or has been revoked.

Solutions:

Verify you're using the correct API key
Ensure the key hasn't been revoked
Check for typos or extra whitespace
Generate a new key if needed

“Too many requests”

You've exceeded the rate limit for API requests.

Solutions:

Check X-RateLimit-Reset header for when to retry
Implement exponential backoff
Reduce request frequency
Cache responses when possible

“Invalid request body”

The request body contains invalid or missing fields.

Solutions:

Check the details field for specific errors
Verify all required fields are included
Ensure data types match (string, number, etc.)
Check for JSON syntax errors

“Resource not found”

The requested resource doesn't exist or has been deleted.

Solutions:

Verify the resource ID is correct
Check if the resource was deleted
Ensure you have access to this workspace
List resources to find the correct ID

Error Handling Best Practices

error-handling.js

async function makeApiRequest(endpoint, options = {}) {
  const response = await fetch(`https://www.nutalk.ai/v1${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${process.env.NUTALK_API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
 
  const data = await response.json();
 
  if (!data.success) {
    const error = data.error;
 
    switch (error.code) {
      case 'rate_limited':
        // Wait and retry
        const resetTime = response.headers.get('X-RateLimit-Reset');
        const waitMs = (parseInt(resetTime) - Date.now()) + 1000;
        await sleep(waitMs);
        return makeApiRequest(endpoint, options);
 
      case 'validation_error':
        // Log validation details for debugging
        console.error('Validation errors:', error.details);
        throw new ValidationError(error.message, error.details);
 
      case 'unauthorized':
      case 'invalid_api_key':
        // Don't retry auth errors
        throw new AuthenticationError(error.message);
 
      case 'internal_error':
        // Retry with exponential backoff
        if (options.retries < 3) {
          await sleep(Math.pow(2, options.retries) * 1000);
          return makeApiRequest(endpoint, {
            ...options,
            retries: (options.retries || 0) + 1
          });
        }
        throw new ServerError(error.message);
 
      default:
        throw new ApiError(error.code, error.message);
    }
  }
 
  return data;
}