Skip to Content
FlowVerifyDevelopers

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

HTTPcodeWhen
400validation_failedA parameter is missing, malformed or out of range; see details.errors[].param
401invalid_api_keyMissing, malformed, unknown, revoked or expired key
403forbiddenKey suspended or API access switched off for the workspace
403insufficient_scopeThe key lacks details.required_scope
403feature_not_availableThe plan lacks the feature (API access, Webhooks, SMS/email OTP, Aadhaar eSign, bulk send); details.feature_key
403plan_limit_exceededMonthly envelope quota or another plan limit reached; details carries the limit and usage
403ip_not_allowedSource IP outside the key's allowlist
404not_foundNo such resource in your workspace. The body is identical for foreign ids
409state_conflictThe 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
409idempotency_conflictA request with this Idempotency-Key is still being processed
413payload_too_largeJSON above 1 MB (36 MB on the file-upload route)
415unsupported_media_typeWrong content type or an unsupported file type
422document_processing_failedThe uploaded document could not be read, converted or certified
422idempotency_mismatchSame Idempotency-Key, different body
429rate_limitedSee below; honour Retry-After
503idempotency_unavailableIdempotent requests briefly unavailable; retry with the same key
503public_api_disabledThe API is temporarily switched off; retry later
500internal_errorSomething 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.

BucketApplies toDefault
StandardEvery endpoint120 requests / minute (a per-key ceiling can be set lower in the console)
Expensivesend, remind, bulk-send, file uploads, send-from-template, webhook test / rotate-secret / replay30 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.

SituationResult
Same key, same body, first request finishedThe original response is replayed, with Idempotent-Replayed: true
Same key, first request still running409 idempotency_conflict — wait and retry
Same key, different body422 idempotency_mismatch
First request failed with a 5xx or was abortedThe 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.

On this page