Developer documentation API v1
Errors, retries and recovery
A caller needs to know both what failed and whether an external effect may already exist.
Problem response
Errors use application/problem+json following RFC 9457. Seer adds code, request_id and retry fields so clients can distinguish validation failures, temporary dependency failures and operations that require reconciliation.
{
"type": "/problems/idempotency-conflict",
"title": "Idempotency conflict",
"status": 409,
"detail": "This key is already bound to a different request.",
"instance": "/v1/requests/req_example_1",
"code": "IDEMPOTENCY_CONFLICT",
"request_id": "req_example_1",
"retry": "none"
}Failure taxonomy
| HTTP / code | Meaning | Recovery |
|---|---|---|
| 400 INVALID_INPUT | The request violates its schema. | Correct the input. |
| 401 UNAUTHENTICATED | The caller’s identity is not established. | Use a valid issued connection. |
| 403 FORBIDDEN | The authenticated caller lacks permission. | Resolve the grant; do not retry unchanged. |
| 404 NOT_FOUND | No accessible resource is returned. | Do not infer another tenant’s resource existence. |
| 409 IDEMPOTENCY_CONFLICT | Same scoped key, different fingerprint. | Recover the original operation and reconcile client intent. |
| 422 INSUFFICIENT_EVIDENCE | Schema is valid but analytical prerequisites fail. | Provide valid coverage or narrow the task. |
| 429 RATE_LIMITED | Admission capacity or request quota is exhausted. | Honor documented retry timing and budget. |
| 503 DEPENDENCY_UNAVAILABLE | Required service is unavailable. | Retry only according to operation and effect state. |
Uncertain effects are resources
If an action is durably accepted but its venue acknowledgment is lost, retain submission_unknown on the action record. A subsequent GET can return 200 with that unresolved state. HTTP success here means the query succeeded, not that the trade succeeded.
If the original HTTP response is lost entirely, recover with the original scoped idempotency key and payload while the documented key binding remains valid. Never create a new key to bypass uncertainty. Beyond that window, establish the existing action through status recovery before another submission is considered.
Bounded retry delay
Transient failures use bounded exponential backoff with full jitter. Bound attempt count and elapsed time, respect server Retry-After where supplied and stop on invalid input or denied authority. A delay policy does not make a non-idempotent financial action safe to retry.
Recovery semantics
Recovery semantics distinguish invalid requests, temporary dependency failures and uncertain external effects. A dependency failure remains an explicit error instead of becoming empty evidence, a zero forecast or presumed available cash.
The action resource preserves uncertainty until an authoritative venue observation resolves it. Retrying the transport request with its original identity retrieves the admitted operation; it does not create permission to replace an unresolved financial effect.
Retry identity versus effect identity
Transport retries repeat a request, while effect identity names the admitted operation. A retry can produce another network attempt without producing another operation when its key and payload resolve to the same admission record. Once the binding has expired, that inference no longer follows from the key alone.
Recovery therefore follows the resource state and external evidence. Validation errors are terminal for the submitted payload. Temporary dependency failures can admit bounded retry when no uncertain effect exists. Reconciliation-first errors preserve the action and committed resources while its outcome is resolved.