Skip to main content

​
HTTP Status Codes

The itellicoAI API uses standard HTTP status codes. Error responses return JSON with:
  • code (machine-readable)
  • message (human-readable)
  • optional detail
  • optional errors (field-level validation issues)

​
Client Errors (4xx)

StatusDefault codeDescriptionCommon Causes
400bad_requestThe request is malformed or invalidInvalid JSON, malformed parameters, unsupported combinations
401unauthorizedAuthentication is missing or invalidMissing X-API-Key, revoked key, expired key
402payment_requiredAccess requires billing/plan entitlementFeature not available on current plan
403forbiddenAuthenticated but not authorizedMissing permission, wrong account selected
404not_foundThe requested resource does not existWrong UUID, deleted resource, wrong path
405method_not_allowedHTTP method not supportedUsing POST instead of PATCH, etc.
409conflictRequest conflicts with current stateDuplicate create, concurrent update conflict
410goneResource no longer availableRemoved/deprecated resource
422validation_errorRequest data failed validationInvalid field values, schema violations
429rate_limit_exceededYou exceeded a rate limitToo many requests in the current window

​
Server Errors (5xx)

StatusDefault codeDescriptionWhat to do
500internal_errorUnexpected server errorRetry. If persistent, contact support with request details
502bad_gatewayUpstream provider/service errorRetry with backoff
503service_unavailableService temporarily unavailableWait and retry
504gateway_timeoutUpstream service timed outRetry with backoff

​
Error Response Format

All API errors follow this structure: 
{
  "code": "not_found",
  "message": "Resource not found",
  "detail": "Agent with UUID 123e4567-e89b-12d3-a456-426614174000 does not exist"
}
Validation failures (422) can include field-level details: 
{
  "code": "validation_error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "body.email",
      "message": "Invalid email format",
      "type": "value_error"
    },
    {
      "field": "body.name",
      "message": "Field required",
      "type": "missing"
    }
  ]
}

​
Common Issues & Solutions

  • Verify the API key is copied correctly (no extra spaces)
  • Check the key hasn’t been revoked in Developers → API Keys
  • Ensure you are using the correct header: X-API-Key: <your-key>
  • Confirm the key format starts with sk-
  • Confirm the key belongs to the right account
  • Verify you are accessing a resource within your own account
  • Check your team role has sufficient permissions
  • For subaccount resources, ensure you are using the correct account
  • Check required fields are included in the request body
  • Verify field values match expected types (string, number, enum)
  • Check enum fields use valid values (refer to the API Reference)
  • Ensure file uploads meet size and format requirements
  • Implement exponential backoff in your integration
  • Check your request volume against rate limits
  • Batch operations where possible to reduce request count
  • Contact support if you need higher limits
  • Retry with exponential backoff (wait 1s, 2s, 4s, 8s…)
  • Check support for any ongoing incidents
  • If the error persists after retries, contact support with the request details

​
Call Disconnection Reasons

When a call ends, the conversation detail shows the disconnection reason. Use this table to understand what happened.

​
Normal Endings

ReasonDescription
user_hangupThe caller hung up — expected behavior
agent_hangupThe AI agent ended the call (e.g., after a closing message)
call_transferThe call was transferred to another agent or phone number
max_durationThe call hit the maximum duration limit you configured
inactivityThe call was ended due to prolonged silence
voicemailVoicemail was detected (outbound campaigns with AMD enabled)

​
Connection Failures (Never Connected)

ReasonDescription
dial_busyThe number was busy
dial_no_answerNobody picked up
dial_failedDialing failed — check the number format and carrier status
dial_rejectedThe recipient rejected the call
invalid_numberThe number is invalid — check E.164 format (+43720123456)

​
System Errors

ReasonDescription
network_errorNetwork issue between itellicoAI and the carrier
provider_errorThe telephony or voice provider returned an error
agent_errorThe AI agent encountered an internal error
concurrency_limitYour plan’s concurrent call limit was reached — retry with backoff or upgrade
unknownUnspecified error — contact support@itellico.ai with the conversation ID

​
Conversation Statuses

StatusMeaning
activeCall is currently in progress
completedCall ended normally
failedCall failed due to an error
transferredCall was transferred to another destination

​
Answer Statuses (Outbound)

StatusMeaning
waitingThe system is still determining who answered
humanA human answered the call
machineAnswering machine detected
user_rejectedRecipient rejected the call
user_unavailableNo answer / timeout
user_busyLine was busy
unknownThe answer outcome could not be determined

​
Next Steps

API Reference

View full API endpoint documentation

API Keys

Create and manage API keys

Limits & Quotas

View rate limits and plan quotas

SDKs

Use official SDKs for built-in error handling