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.
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-Idheader. Include it when you contact us.
Error types
| type | HTTP status | What to do |
|---|---|---|
invalid_request | 400, 413, 415 | The request is malformed or a value is wrong. Fix it before retrying. |
authentication | 401 | No token, or it expired or was revoked. Get a new token and retry once. |
permission | 403 | Authenticated, but not allowed: a missing scope, an IP allowlist, an inactive account or a sandbox key. Retrying won’t help. |
not_found | 404 | No such endpoint, or no such object in this account. Ids from another account are always “not found”. |
conflict | 409 | It clashes with something that exists, like a contact with that phone number or a booked time. |
rate_limit | 429 | Too many requests. Wait Retry-After seconds. See Rate limits. |
server | 500, 502, 503 | Something failed on our side or timed out. Retry with backoff; contact us if it persists. |
Common codes
| Code | Status | Meaning |
|---|---|---|
missing_token | 401 | No Authorization header. |
invalid_token | 401 | The access token is malformed, expired or revoked. |
invalid_client | 401 | Wrong client ID or secret at the token endpoint, or the key was revoked. |
insufficient_scope | 403 | The token doesn’t have the scope this endpoint needs. |
ip_not_allowed | 403 | The key’s IP allowlist doesn’t include this address. |
account_inactive | 403 | The account (or partner) isn’t active, or you tried to change a client that isn’t. |
sandbox_read_only | 403 | Sandbox keys can’t change anything. |
account_required | 400 | A partner key called an account endpoint without the AssistCall-Account header. |
parameter_invalid | 400 | A parameter or field has the wrong type or value. The message names it. |
unknown_parameter | 400 | A query parameter or body field the endpoint doesn’t accept. Unknown fields are refused, not ignored, so typos surface. |
invalid_json | 400 | The body isn’t valid JSON. |
invalid_cursor | 400 | The cursor wasn’t a next_cursor from this list. |
payload_too_large | 413 | The body is over 100 KB. |
unsupported_media_type | 415 | Send bodies as JSON with Content-Type: application/json. |
resource_missing | 404 | No such object in this account. |
route_not_found | 404 | No such endpoint. Check the method and path. |
contact_exists | 409 | A contact with that phone number already exists. |
slot_taken | 409 | The appointment time overlaps another appointment. |
email_taken | 409 | Partner API: someone with that owner email already has an account. |
rate_limited | 429 | Over the per-minute limit. |
daily_quota_exceeded | 429 | Over the daily quota; it resets at midnight UTC. |
timeout | 503 | The request took too long (25 seconds at most). Retry. |
server_error | 500 | An 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 oncodewhere you need to), never onmessage. - Retry
rate_limitandservererrors with backoff. Don't retryinvalid_request,permissionornot_foundunchanged. - 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.