Errors and recovery
Turn API failures into clear next steps, and distinguish safe reads from ambiguous writes.
Read the status and body together
The current API uses several success and error envelopes. Some paths include error.message, type, code, and request_id; others use response_message or errors.msg. Match the operation’s reference rather than assuming one global shape.
{
"response": "Fail",
"response_message": "Invalid signing_type \"gnw\". Allowed values: ron, esign, ipen.",
"error": {
"message": "Invalid signing_type \"gnw\". Allowed values: ron, esign, ipen.",
"type": "validation_error",
"code": "invalid_signing_type",
"request_id": "EXAMPLE_REQUEST_ID"
}
}Use the operation’s actual status contract
A generic HTTP table cannot capture every current endpoint behavior.
| Status | Typical next step |
|---|---|
| 400 | Correct the request, invalid identifier, or unsupported state. |
| 401 | Repair missing, expired, or invalid credentials. |
| 403 | Check vendor ownership, missing/deleted session, or closed upload state. |
| 404 | Some team/access operations use this for missing resources. |
| 409 | Inspect duplicate linkage, state race, merge lock, or partial result. |
| 413 | Reduce payload and confirm the applicable gateway/endpoint budget. |
| 429 | Reduce request rate and use bounded backoff. |
| 5xx | Investigate whether a write already completed before replaying. |
Treat an ambiguous write carefully
If create-session times out, the server may have created a session before the connection failed. Create Session does not provide a documented idempotency guarantee. Reusing notarization_id alone does not guarantee duplicate prevention.
- Retain context
Record order reference, request time, returned IDs if any, and non-sensitive diagnostics.
- Reconcile
Inspect available session and account logs to determine whether work completed.
- Retry deliberately
Repeat only when the operation’s outcome and duplicate consequences are understood.
Diagnose successful creates with unexpected behavior
A 200 response can still leave an account-configuration issue to resolve.
| Symptom | Check first |
|---|---|
| No open call | Effective routing, dispatch trigger, disabling gates, and preparation hold. |
| Unexpected internal/network pool | Account routing policy. |
| Scheduled call fires early | Strict scheduling and notification lead-time policy. |
| Signer email missing | Product-specific invitation switch and suppression settings. |
| Named notary rejected | Business linkage, pending approval, and state eligibility. |
| No final PDFs yet | Processing readiness and selected delivery channel. |
Inspect partial document outcomes
An upload can attach some documents before a failure. A closure race can report stored and requested counts; other per-file failures need further reconciliation. Do not assume a generic upload 200 proves all requested fields were applied.
Keep actionable diagnostics
A useful support record identifies the operation without exposing customer credentials or documents.
- HTTP method, route, timestamp, response status, and non-sensitive error code.
- bn_session_id and your correlation reference when available.
- request_id for API errors that provide it.
- delivery_id and req_id for managed webhook diagnosis.
- Account/environment context and the selected workflow.
- Redacted headers and access URLs; never share the API key.
Plan traffic and retries
The application limiter is per resolved client IP, with exceptions; confirm the effective deployed quota and gateway limits for your account. Coordinate services sharing a NAT address. Use backoff for retryable reads and deliveries, while applying the write-reconciliation rules above.