Skip to content

Errors and limits

Errors have an HTTP status and a body with a stable code to branch on and a message to show a person:

{ "error": { "code": "insufficient_credits", "message": "This project needs 41 min of credits and the account has 12 min." } }
StatusMeansSome codes
400The request is wrong. validation_error lists the fields in details.validation_error, invalid_file_count, video_in_project, invalid_merge, invalid_source, duplicate_file, invalid_url, invalid_cursor, unknown_show, show_archived, unknown_destination, too_many_destinations, invalid_target, unknown_bundle, invalid_threshold, invalid_cap
401No key, an invalid or revoked key, or its creator left the account.
402Payment needed: not enough credits for Keep’s fee, or the card was declined.insufficient_credits, card_declined
403The key can’t do this.missing_scope, test_mode, account_suspended, show_limited, invoice_billing_off, user_only, not_for_apps
404Not found, or not yours (another account’s, the other mode’s, or another show’s for a key limited to one).not_found, file_not_found
409It conflicts with the current state.invalid_transition, duplicate_client_ref, file_expired, file_failed, file_in_use, idempotency_key_reused, endpoint_limit, duplicate_show, show_limit, destination_limit, files_gone, no_saved_card, invoice_overdue, invoice_limit_reached
413The body is over 1 MB.payload_too_large
429Too many requests or a limit reached.rate_limited, test_limit_reached, import_limit, upload_limit
5xxOur fault. Retry with backoff (safely, with an Idempotency-Key).

Request bodies take only the fields this reference lists: anything else (a typo, or a field from another shape, such as url where a file’s source belongs) is 400 validation_error, with the field named in details, rather than ignored. The same goes for the keys of a file’s source.

A project that validation refuses isn’t an error response: it’s rejected with a rejection.code (see Projects).

120 requests a minute per key. Over that you get 429 rate_limited with a Retry-After header (seconds). Poll a project every 10 seconds or so, or use webhooks.

Send an Idempotency-Key header (any unique string up to 255 characters) on a POST to make retrying it safe. Within 24 hours, the same key with the same body returns the first response again, with Idempotent-Replayed: true, instead of acting twice. The same key with a different body is 409 idempotency_key_reused; a retry while the first request is still running is 409 idempotency_in_progress. A 5xx isn’t kept, so retrying it runs again. Keys belong to the API key that sent them.

Terminal window
curl https://api.podsworth.com/v1/projects \
-H "Authorization: Bearer $PODSWORTH_KEY" -H "Idempotency-Key: ep-12-create" \
-H "Content-Type: application/json" -d '{"files": [{"fileName": "ep12.wav"}]}'

Lists (/v1/projects, /v1/events, deliveries) return the newest first and a nextCursor; pass it back as cursor for the next page, until it’s null. limit is 20 by default, at most 100.