Errors & Limits

Error responses

Errors use RFC 9457 Problem Details with the application/problem+json content type:

{
  "type": "https://api.ardela.ai/problems/resource-not-found",
  "title": "Recording not found",
  "status": 404,
  "code": "RESOURCE_NOT_FOUND",
  "requestId": "req_123"
}

Use code for application logic, title for a short human-readable summary, and requestId when contacting Ardela support.

HTTP status codes

Code	Example problem code	Cause
`400`	`INVALID_INPUT`	Invalid query parameters or request body
`400`	`INVALID_CURSOR`	Invalid or expired pagination cursor
`400`	`IDEMPOTENCY_KEY_REQUIRED`	Missing or invalid webhook idempotency key
`401`	`UNAUTHORIZED`	Missing, invalid, or revoked API key
`403`	`INSUFFICIENT_SCOPE`	API key lacks the required scope
`403`	`SUBSCRIPTION_REQUIRED`	Workspace does not have an eligible active subscription
`404`	`RESOURCE_NOT_FOUND`	Resource does not exist in the key's workspace
`409`	`RECORDING_NOT_COMPLETED`	Filing a recording that is not `COMPLETED`
`409`	`WEBHOOK_SUBSCRIPTION_LIMIT_EXCEEDED`	Workspace already has 50 webhook subscriptions
`415`	`UNSUPPORTED_CONTENT_TYPE`	Request body is not `application/json`
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests per minute
`500`	`INTERNAL_ERROR`	Server-side failure

Validation errors do not expose field-level details.

Rate limits

120 requests per minute per workspace.

When exceeded, the API returns 429. Pause requests and retry with exponential backoff and jitter.

Best practices

Security

Never expose API keys in client-side code, mobile apps, or public repositories
Use HTTPS only
Rotate keys according to your organisation's credential policy and immediately if a key is exposed
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
Choose a polling interval that meets your workflow needs without approaching the per-minute limit
Combine webhooks (fast) with polling (reliable recovery)

Idempotency

Filing with the same provider + externalId is safe to retry
Use recording id as your deduplication key in custom automations

Error handling

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

On this page