Error Codes

All errors look the same.

{ "error": { "code": "not_found", "message": "Conversation not found" } }

Handle errors by code. The codes below don't change.
message is for people and can change. For validation_error it names the field.
A request without an Authorization header can get a 429 with a different body. See Rate Limits.

Codes

Code	Status	Meaning	What to do
`validation_error`	400	A field or parameter is missing or wrong, or the body isn't valid JSON. Feedback also returns it for a call with fewer than 10 transcript segments.	Fix the request
`unauthorized`	401	The `Authorization` header is missing, or the key is wrong or revoked	See Authentication
`forbidden`	403	The plan doesn't allow the request. This covers a Free plan or ended subscription, webhooks below Professional, the webhook limit, a contact briefing without Convo Memory, revoked calendar access, and a key from an MCP sign-in.	Read the message
`not_found`	404	No such call, webhook or contact in your account, or the call was deleted. Also returned when key points or feedback don't exist yet, when renaming a call without key points, and when no calendar is connected.	Check the ID. Generate key points or feedback with `POST`.
`rate_limited`	429	Over the hourly request limit, or the AI model is busy	Wait `Retry-After` seconds, or a few seconds when there is no header
`ai_limit_exceeded`	429	Your AI credits are used up for the month or the day, or the spending cap is reached	Don't retry. See Tier Access.
`internal_error`	500	Something failed on Convo's side	Retry once after a pause

Retry rate_limited and internal_error. Every other code means the request or the account has to change first.
On POST /feedback, /query and /email, a 500 can come after the AI credit was used, so a retry uses another one.
If an error persists, write to ivan@itsconvo.com with the endpoint, the time and the message.