Errors and limits

Status codes, error bodies, rate limits and idempotency.

Errors return JSON: { "error": { "type", "code", "message", "param" } }. The message is written for a person.

• 400 invalid_request: a field is missing or malformed; param names it.
• 401 unauthorized: no key, a malformed key, or a revoked key.
• 402 live_dialing_inactive: a live key tried to dial before live dialing was activated.
• 403 forbidden: the key's scope does not allow this, or the dial mode is not allowed by your policy.
• 404 not_found: no such object in this environment (test and live are separate).
• 409 conflict: an object with that external id already exists.
• 422 outside_calling_hours or do_not_call: a live dial was refused before anything rang.
• 429 rate_limited: slow down; Retry-After says for how long.

Idempotency

Send an Idempotency-Key header on any POST. The same key within 24 hours returns the first response instead of doing the work twice.