Every error has the same shape: a stable code to branch on, a message for a human, and the request_id to quote to support. Some also carry a details object. Branch on code, never on the message, which may be reworded.
{
"error": {
"code": "insufficient_credits",
"message": "This organization has no credits left.",
"request_id": "req_0Nq8c1xWv3kR"
}
}Charged or not
No error in this table is charged. The only call that costs credits is one that returns a 200 with a transcript.
Which errors to retry
- Retry with backoff: 429, 503 and 504. Honour
Retry-Afterwhen present. With anIdempotency-Keythis is always safe. - Retry once, then report: 502 and 500.
- Do not retry: other 4xx. They need a change on your side (a key, a balance, a field).
- 409
idempotency_key_usedis not a failure. The first attempt succeeded and was billed.
All error codes
401
missing_api_key
No Authorization header and no x-api-key header.
Send the key as a bearer token.
401
invalid_api_key
The key is not recognised, or does not start with hohe_.
Check the key, including the hohe_ prefix.
401
api_key_revoked
The key existed and was disabled.
Use a different key. Revocation takes effect on the next request, never later.
401
api_key_expired
The key passed its expiry.
Use a key that has not expired.
402
no_credit_account
The organization has no credit account.
Add credits. Nothing ran and nothing was charged.
402
insufficient_credits
Balance plus overdraft is zero or less.
Add credits. Nothing ran and nothing was charged. The details object carries balance and overdraftLimit.
400
invalid_request
A field or header failed validation, or the multipart body could not be parsed. The message names the field.
Fix the field named in the message. The details array lists each failing path.
413
file_too_large
The upload is over the size limit.
Split the audio. The limit is stated in the message (25 MiB by default).
415
unsupported_content_type
The body was not multipart/form-data.
Send the audio as a multipart field named file, not as a raw body or base64 JSON.
415
unsupported_audio
The model host could not read the container or codec.
Re-encode the audio to a common format and retry. Nothing was charged.
422
invalid_audio
The file was readable but cannot be transcribed. The message says why.
Check it is the file you meant to send. Nothing was charged.
409
idempotency_key_used
That Idempotency-Key was already billed.
Read the details object: it carries the original usage event, units and credits charged. Use a new key to run the audio again.
409
request_in_progress
A request with the same Idempotency-Key is running right now.
Wait, then retry with the same key.
429
rate_limited
The key's rate limit was exceeded.
Wait the number of seconds in Retry-After.
413
request_too_large
One request exceeded the per-request cap for this operation.
Read the details object for the limit and what was counted, then split the input.
429
organization_busy
Your organization already has as many requests in flight as it is allowed.
Wait for one to finish, or ask support to raise the limit.
429
daily_limit_reached
Your organization's rolling 24 hour credit cap is spent.
Raise or clear the cap in the dashboard, or wait for the window to roll.
503
server_busy
Too many uploads in flight on this server.
Retry after the Retry-After seconds. Nothing was charged.
503
inference_unavailable
The model host could not be reached or returned a server error.
Retry after the Retry-After seconds. Nothing was charged.
504
inference_timeout
The model host took too long.
Retry, or send a shorter clip. Nothing was charged.
502
bad_upstream_response
The model host returned something unusable.
Retry. Nothing was charged.
503
pricing_unavailable
No price is configured for the operation.
Retry later, or contact support. Nothing was charged.
503
metering_unavailable
The call could not be billed, so the result was withheld.
Retry with the same Idempotency-Key. Nothing was charged.
404
not_found
No such endpoint.
Check the path.
500
internal_error
An unexpected failure on our side. The message is always generic.
Quote the request_id to support.