Error Handling

The TalkPilot API uses standard HTTP status codes and returns structured error responses to help you handle failures gracefully.

Error response format

Every error response follows this structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong",
    "details": [],
    "request_id": "req_abc123"
  }
}

Field	Type	Description
`code`	string	Machine-readable error code (see table below)
`message`	string	Human-readable description
`details`	array	Field-level validation errors (only for `VALIDATION_ERROR`)
`request_id`	string	Unique request ID for debugging — include this when contacting support

HTTP status codes

Status	Code	Description
`400`	`VALIDATION_ERROR`	Request body failed validation
`400`	`BAD_REQUEST`	Malformed request (invalid JSON, missing headers, etc.)
`401`	`UNAUTHORIZED`	Missing, invalid, inactive, or expired API key
`403`	`FORBIDDEN`	API key lacks required permission
`404`	`NOT_FOUND`	Resource does not exist or is not accessible
`409`	`CONFLICT`	Resource already exists (e.g., duplicate tool name)
`429`	`RATE_LIMITED`	Too many requests — see Rate Limiting
`500`	`INTERNAL_ERROR`	Server error — retry or contact support

Validation errors

When a request fails validation, the details array contains field-level errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "field": "name", "message": "Required" },
      { "field": "phone_number", "message": "Must be a valid E.164 phone number" },
      { "field": "status", "message": "Must be one of: anwesend, urlaub, krank, weiterbildung, notdienst" }
    ],
    "request_id": "req_abc123"
  }
}

Handling errors in code

JavaScript / TypeScript

async function makeApiRequest(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  if (!response.ok) {
    const body = await response.json();
    const error = body.error;

    switch (response.status) {
      case 401:
        throw new Error(`Authentication failed: ${error.message}`);
      case 403:
        throw new Error(`Permission denied: ${error.message}`);
      case 404:
        return null; // Resource not found
      case 429:
        // Wait and retry
        const retryAfter = response.headers.get("Retry-After") || 60;
        await new Promise((r) => setTimeout(r, retryAfter * 1000));
        return makeApiRequest(url, options);
      default:
        throw new Error(`API error [${error.code}]: ${error.message} (${error.request_id})`);
    }
  }

  return response.json();
}

Python

import requests
import time

def make_api_request(url, method="GET", data=None):
    response = requests.request(
        method, url,
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json=data,
    )

    if response.ok:
        return response.json() if response.content else None

    error = response.json().get("error", {})

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        time.sleep(retry_after)
        return make_api_request(url, method, data)

    if response.status_code == 404:
        return None

    raise Exception(
        f"API error [{error.get('code')}]: {error.get('message')} "
        f"(request_id: {error.get('request_id')})"
    )

Debugging tips

Check the request_id — Include it when contacting support for faster resolution
Read details for validation errors — They tell you exactly which fields failed and why
Check rate limit headers — If you’re getting 429s, inspect X-RateLimit-Remaining before retrying
Verify permissions — 403 errors always include the missing permission in the message

API Resources

Guides

Code Examples

Error response format

HTTP status codes

Validation errors

Handling errors in code

JavaScript / TypeScript

Python

Debugging tips

​Error response format

​HTTP status codes

​Validation errors

​Handling errors in code

​JavaScript / TypeScript

​Python

​Debugging tips

Error response format

HTTP status codes

Validation errors

Handling errors in code

JavaScript / TypeScript

Python

Debugging tips