Errors

Errors use the standard envelope:

{
	"error": {
		"code": "validation",
		"message": "The request body failed validation; `fields` maps each invalid field to a stable message key.",
		"retryable": false,
		"requestId": "0f9c2e5a-8f4b-4d61-9a3e-2c7d1b5f0a44",
		"fields": { "url": "url_invalid" }
	}
}

• message explains what happened in plain text. It is the field to read while integrating, and the one to keep in your logs.
• code identifies the kind of error and is what your code should branch on: always one of the codes below, never an arbitrary string.
• retryable says whether repeating the SAME request can succeed. It is the one decision the HTTP status does not answer on its own: a 429 is worth repeating, a 409 from idempotency never will be. Branch on it instead of keeping your own table of which errors deserve a retry.
• requestId identifies this response, and is also in the X-Request-Id header. Keep it in your logs: it is how we find, on our side, what happened on that exact call.
• fields (only on validation) points to a stable key per invalid field.

retryable: true does not mean "retry now": on rate_limited the Retry-After header says when, and elsewhere exponential backoff with jitter applies.

Codes

The API reference documents, per endpoint, exactly which codes each status can return.

Rate limits

Every response from a limited route carries the three headers, not just the 429:

They are what lets you slow down BEFORE hitting the ceiling instead of finding it by being refused. 429 rate_limited also carries Retry-After with the real wait, in seconds. The ceilings are per account, on a sliding window:

A backlog releasing all at once reaches these easily, because a customer's peak looks nothing like their average traffic. Spread the burst over the Retry-After wait instead of retrying immediately; nothing is lost, only delayed. If you need more, talk to us before the migration starts.

Validation keys

Transcript failures

When a transcript ends in status: "failed", its error field carries { code, message } with the reason. Failed transcripts are never charged.

status: "canceled" is not a failure: it is a transcript you stopped with POST /v1/transcripts/{id}/cancel. It is terminal, error stays null, and nothing is charged.