Errors and limits

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, invalid_url, invalid_cursor
401	No key, an invalid or revoked key, or its creator left the account.
403	The key can’t do this.	missing_scope, test_mode, account_suspended
404	Not found, or not yours (another account’s, or the other mode’s).	not_found
409	It conflicts with the current state.	invalid_transition, duplicate_client_ref, idempotency_key_reused, endpoint_limit
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
5xx	Our fault. Retry with backoff (safely, with an Idempotency-Key).

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

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

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

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.