Errors, rate limits and idempotency
The one error shape, every stable code, the two rate-limit buckets and how Idempotency-Key works.
Error shape
Every error, from every endpoint, has the same body:
{
"success": false,
"code": "validation_failed",
"message": "The request is invalid.",
"request_id": "fa9ab28f-6eb0-4141-b526-7f3dc110d869",
"details": {
"errors": [
{ "param": "recipients[0].email", "message": "email must be a valid address" }
]
}
}code is stable and safe to branch on; message is for humans and may change. details is present when there is something structured to say (validation errors list the failing param, never the submitted value). Quote request_id (also sent as the X-Request-Id header on every response) when you contact support.
Codes
| HTTP | code | When |
|---|---|---|
| 400 | validation_failed | A parameter is missing, malformed or out of range; see details.errors[].param |
| 401 | invalid_api_key | Missing, malformed, unknown, revoked or expired key |
| 403 | forbidden | Key suspended or API access switched off for the workspace |
| 403 | insufficient_scope | The key lacks details.required_scope |
| 403 | feature_not_available | The plan lacks the feature (API access, Webhooks, SMS/email OTP, Aadhaar eSign, bulk send); details.feature_key |
| 403 | plan_limit_exceeded | Monthly envelope quota or another plan limit reached; details carries the limit and usage |
| 403 | ip_not_allowed | Source IP outside the key's allowlist |
| 404 | not_found | No such resource in your workspace. The body is identical for foreign ids |
| 409 | state_conflict | The resource is not in a state that allows this (sending a sent envelope, a signer without fields, a bulk send already running, replaying on a paused webhook); details.reason when known |
| 409 | idempotency_conflict | A request with this Idempotency-Key is still being processed |
| 413 | payload_too_large | JSON above 1 MB (36 MB on the file-upload route) |
| 415 | unsupported_media_type | Wrong content type or an unsupported file type |
| 422 | document_processing_failed | The uploaded document could not be read, converted or certified |
| 422 | idempotency_mismatch | Same Idempotency-Key, different body |
| 429 | rate_limited | See below; honour Retry-After |
| 503 | idempotency_unavailable | Idempotent requests briefly unavailable; retry with the same key |
| 503 | public_api_disabled | The API is temporarily switched off; retry later |
| 500 | internal_error | Something failed on our side; retry once, then contact support with the request_id |
Rate limits
Limits are per API key and per minute, never per IP, so several servers behind one egress do not compete.
| Bucket | Applies to | Default |
|---|---|---|
| Standard | Every endpoint | 120 requests / minute (a per-key ceiling can be set lower in the console) |
| Expensive | send, remind, bulk-send, file uploads, send-from-template, webhook test / rotate-secret / replay | 30 requests / minute |
Every response carries RateLimit headers (limit, remaining, reset, IETF draft-7 format); a 429 rate_limited adds Retry-After (seconds) and details.scope (standard or expensive). Back off until Retry-After has passed; do not retry 429s in a tight loop.
Unauthenticated failures are additionally throttled per IP; repeated invalid keys get an IP blocked at the edge.
Idempotency
Send Idempotency-Key (8–128 characters: letters, digits, _, -, :, .) on any request that creates or sends — envelope create, send, remind, bulk send, send-from-template, webhook create. The key is scoped to your workspace, your API key and the path, and remembered for 24 hours.
| Situation | Result |
|---|---|
| Same key, same body, first request finished | The original response is replayed, with Idempotent-Replayed: true |
| Same key, first request still running | 409 idempotency_conflict — wait and retry |
| Same key, different body | 422 idempotency_mismatch |
| First request failed with a 5xx or was aborted | The key is released; retry normally |
Multipart uploads are not replayed. Derive keys from your own records (order-1042-send), not from timestamps.
Retrying safely
- Network errors and 5xx: retry with exponential backoff, reusing the
Idempotency-Key. - 429: wait for
Retry-After. - 4xx other than 409/429: fix the request; retrying the same call will fail the same way.