Errors and limits
Errors
Section titled “Errors”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." } }| Status | Means | Some codes |
|---|---|---|
400 | The 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 |
401 | No key, an invalid or revoked key, or its creator left the account. | |
402 | Payment needed: not enough credits for Keep’s fee, or the card was declined. | insufficient_credits, card_declined |
403 | The key can’t do this. | missing_scope, test_mode, account_suspended, show_limited, invoice_billing_off, user_only, not_for_apps |
404 | Not 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 |
409 | It 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 |
413 | The body is over 1 MB. | payload_too_large |
429 | Too many requests or a limit reached. | rate_limited, test_limit_reached, import_limit, upload_limit |
5xx | Our 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).
Rate limits
Section titled “Rate limits”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.
Idempotent retries
Section titled “Idempotent retries”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.
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"}]}'Pagination
Section titled “Pagination”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.