Errors & Limits

Error responses

Errors return JSON with an error message string:

{ "error": "Recording not found" }

HTTP status codes

Validation errors return a generic Invalid input message — field-level details are not exposed.

Rate limits

120 requests per minute per workspace.

When exceeded, the API returns 429 with a Retry-After header (seconds until reset). Implement exponential backoff in your integration.

Monthly API request limits also apply per plan (separate from per-minute rate limiting). Exceeding the monthly quota returns 403.

Best practices

Security

• Never expose API keys in client-side code, mobile apps, or public repositories
• Use HTTPS only
• Rotate keys every 90 days
• Use separate keys for development and production
• Revoke keys when integrations are decommissioned

Performance

• Poll syncState=unsynced to avoid reprocessing filed recordings
• Use cursor pagination (meta.nextCursor) for catch-up jobs
• Fetch GET /recordings/:id for full content instead of include=content on list endpoints
• Recommended poll interval: 5–15 minutes
• Combine webhooks (fast) with polling (reliable recovery)

Idempotency

• Filing with the same provider + externalId is safe to retry
• Use recording id as your dedupe key in Zapier and similar tools

Error handling

• Retry 429 and 500 with exponential backoff
• Do not retry 400, 401, 403, or 404 without fixing the request
• Log x-ardela-delivery header values when debugging webhooks

Related

• Authentication
• Recordings API
• Webhooks