Errors
Partner-backed operations return application/problem+json:
{
"type": "https://peoplescourt.ai/problems/validation_failed",
"title": "Validation Failed",
"status": 422,
"code": "validation_failed",
"detail": "The request does not satisfy the contract.",
"requestId": "req_9fe76389-b3c1-47cb-81a3-832478d2b8e9"
}| Status | Meaning | Retry guidance |
|---|---|---|
400 | Malformed request or missing required header | Fix the request |
401 | Missing or invalid credential/proof | Reauthenticate |
403 | Credential lacks the role, side, membership, or authority | Do not retry unchanged |
404 | Resource absent or deliberately hidden by tenant scoping | Verify tenant and identifier |
409 | State, digest, revision, idempotency, or phase conflict | Fetch current state first |
413 | Request or transactional evidence payload too large | Reduce the request |
422 | Well-formed request violates the API contract | Fix validation errors |
429 | Rate limit reached | Retry with backoff |
503 | Feature or dependency unavailable | Retry only when appropriate |
Treat code as the stable machine branch. Log requestId, never bearer credentials, invitations, party capabilities, wallet signatures, or evidence bytes.
The message resource additionally returns message_rate_limit_exceeded after 20 writes by one credential to one case in a rolling hour.
Settlement binding registration returns settlement_binding_registration_closed outside awaiting_submissions or awaiting_validation, or once an Award exists. A concurrent allowed-state mutation returns case_revision_conflict. Reusing the original successful idempotency key and body bypasses mutable-state validation and replays the stored response.
New filing packets return acceptance_required (409) until the claimant supplies a matching acceptance. details.termsDigest identifies the exact packet. Authorized claimant callers also receive details.reviewPacket and a newly issued, show-once details.hostedAcceptanceUrl; previous links are invalidated. Keep the URL fragment private. filing_packet_changed requires preparation and acceptance of a fresh packet.
Account OAuth errors
Account operations can return an OAuth error envelope with error and error_description. Handle that envelope separately from partner code errors. A missing account session returns login_required; expired consent requires authorization again. A disabled canonical route can return an empty 404 response. Check status and content type before parsing JSON.
Retry an uncertain request
For a timeout or retryable server failure, keep the original body and Idempotency-Key. Do not create a new key to recover an unknown outcome. For 409, read the resource and resolve the reported conflict before starting a changed request with a new key. On 429, honor Retry-After when present, then use bounded exponential backoff with jitter. See rate limits.