FirmARDigital

Developer documentation

API reference · Errors

Errors and retries

Responses keep a stable shape so you can centralize error handling in your SDK or backend.

Format

jsonFirmARDigital API
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key does not have the required permission"
  }
}
HTTPCategoryAction
400Invalid requestFix `data`, the file type, or required fields. Do not retry without changing it.
401INVALID_API_KEYCheck that the header uses Bearer and the key has not been revoked.
403INSUFFICIENT_SCOPECreate an API key with the scope required by the endpoint.
402LIMIT_REACHEDThe workspace reached its contracted limit. No technical retry can resolve this.
404NOT_FOUNDConfirm the ID and that the key belongs to the same environment: test and live are isolated.
409SIGNER_NOT_ENROLLED or DOCUMENT_NOT_SIGNEDWait for the required status; do not force the flow forward.
410ENROLLMENT_EXPIREDGenerate a new enrollment for the signer.
422IDENTITY_REJECTEDIdentity verification was rejected. Ask the signer to complete a new verification.
503DOCUMENT_STORAGE_NOT_READYRetry the download GET after a few seconds; use backoff and do not recreate the session.

Best practices

  • Retry only network errors or `503` with backoff.
  • Keep the same `Idempotency-Key` when repeating a creation.
  • Do not retry validation errors without changing the request.
  • Persist `x-firmar-event-id` before processing a webhook.
  • Use the status endpoint for reconciliation if a webhook did not reach your infrastructure.