Errors and retries
Every error has the same shape. The fix always says what to do.
{"error": {"type": "insufficient_credits", "message": "This costs $0.04 and the account has $0.00 of credit.", "fix": "Add credits on your account page (from $20), then retry with the same Idempotency-Key."}}
| Status | type |
Meaning |
|---|---|---|
| 400 | invalid_parameter |
A query parameter has the wrong type, e.g. limit=abc. |
| 400 | missing_file, unexpected_file, empty_file, too_few_takes, nothing_to_check, costume_without_reference, invalid_size, invalid_fps, missing_progress, invalid_progress, too_many_frames, different_files, invalid_url |
Something in the request needs changing; fix says what. |
| 401 | missing_api_key, invalid_api_key |
Send Authorization: Bearer rk_… with a current key. |
| 402 | insufficient_credits |
Not enough credit for this check. Nothing was charged. |
| 402 | spend_cap_reached |
The key's monthly cap would be exceeded. Raise it on the account page. |
| 404 | not_found, report_expired |
No such check on this account, or its report passed its retention period. |
| 409 | idempotency_key_reused, not_finished |
The key was used for a different request; or the check hasn't finished. |
| 413 | file_too_large |
Video over 2 GB or image over 30 MB. |
| 415 | unsupported_file, multipart_required |
Wrong file type, or the body isn't multipart. |
A check that can't run (an unreadable video, references with no usable face) finishes with state: "error" and an error object instead. Its reservation is released, so you aren't charged.
Retries
Send an Idempotency-Key header (any unique string, e.g. a UUID) with every POST. If the network fails and you retry with the same key and the same request, you get the first response back, with the header Idempotent-Replayed: true, and you're charged once. Reusing a key for a different request is refused with 409. After a 402, add credit and retry with the same key. The SDK does all of this for you.
Money
Every check reserves its price before it runs and settles the actual cost when it finishes. A check that fails to run releases its reservation in full. Your balance can never go below zero.