Skip to content

DevelopersEssentials

Errors

Errors use standard HTTP status codes and always have the same JSON body: a broad type to branch on, a specific code, a sentence you can show or log, and the request's id.

On this page

The error object

{
  "error": {
    "type": "invalid_request",
    "code": "parameter_invalid",
    "message": "starts_at: Invalid ISO datetime",
    "request_id": "req_7Gm2kQ9xT4vB8nR1sW6yL3pD"
  }
}
type
One of the seven types below. Stable: safe to branch on.
code
A specific reason, like insufficient_scope or slot_taken. Stable once published; new codes can be added, so handle unknown ones by their type.
message
Plain English, written to help you fix the request. It can change: don’t parse it.
request_id
The same value as the Request-Id header. Include it when you contact us.

Error types

typeHTTP statusWhat to do
invalid_request400, 413, 415The request is malformed or a value is wrong. Fix it before retrying.
authentication401No token, or it expired or was revoked. Get a new token and retry once.
permission403Authenticated, but not allowed: a missing scope, an IP allowlist, an inactive account or a sandbox key. Retrying won’t help.
not_found404No such endpoint, or no such object in this account. Ids from another account are always “not found”.
conflict409It clashes with something that exists, like a contact with that phone number or a booked time.
rate_limit429Too many requests. Wait Retry-After seconds. See Rate limits.
server500, 502, 503Something failed on our side or timed out. Retry with backoff; contact us if it persists.

Common codes

CodeStatusMeaning
missing_token401No Authorization header.
invalid_token401The access token is malformed, expired or revoked.
invalid_client401Wrong client ID or secret at the token endpoint, or the key was revoked.
insufficient_scope403The token doesn’t have the scope this endpoint needs.
ip_not_allowed403The key’s IP allowlist doesn’t include this address.
account_inactive403The account (or partner) isn’t active, or you tried to change a client that isn’t.
sandbox_read_only403Sandbox keys can’t change anything.
account_required400A partner key called an account endpoint without the AssistCall-Account header.
parameter_invalid400A parameter or field has the wrong type or value. The message names it.
unknown_parameter400A query parameter or body field the endpoint doesn’t accept. Unknown fields are refused, not ignored, so typos surface.
invalid_json400The body isn’t valid JSON.
invalid_cursor400The cursor wasn’t a next_cursor from this list.
payload_too_large413The body is over 100 KB.
unsupported_media_type415Send bodies as JSON with Content-Type: application/json.
resource_missing404No such object in this account.
route_not_found404No such endpoint. Check the method and path.
contact_exists409A contact with that phone number already exists.
slot_taken409The appointment time overlaps another appointment.
email_taken409Partner API: someone with that owner email already has an account.
rate_limited429Over the per-minute limit.
daily_quota_exceeded429Over the daily quota; it resets at midnight UTC.
timeout503The request took too long (25 seconds at most). Retry.
server_error500An unexpected error. Retry with backoff.

Each endpoint in the API reference lists the errors it can return.

Handling errors

curl -i https://api.assistcall.ai/v1/calls/not-a-real-id \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN"
# HTTP/1.1 404 Not Found
# Request-Id: req_7Gm2kQ9xT4vB8nR1sW6yL3pD
# {"error":{"type":"not_found","code":"resource_missing","message":"No such call.","request_id":"req_7Gm2kQ9xT4vB8nR1sW6yL3pD"}}
  • Branch on type (and on code where you need to), never on message.
  • Retry rate_limit and server errors with backoff. Don't retry invalid_request, permission or not_found unchanged.
  • Check a request's status before reading its body as data: an error body is not a list.

Request ids

Every response, successful or not, has a Request-Id header like req_7Gm2kQ9xT4vB8nR1sW6yL3pD. Log it with your own records. If something looks wrong, email it to [email protected] and we can find that exact request. Your dashboard's Developers page also lists your last 50 requests with their status and timing.

Try "token", "webhook signature", "rate limit" or "custom domain".