API errors use a consistent envelope. Read the HTTP status first, then the error code and message. Keep the request ID so the specific call can be traced without sending credentials or participant answers to support.
{"error":{"code":"validation_failed","message":"Request validation failed","requestId":"example-request-id"}}
The envelope may also include details. Its content depends on the failure. Do not assume every error has a field-by-field explanation.
Choose the correct recovery
| Status | Meaning | Next action |
|---|---|---|
| 400 | Malformed request | Fix parsing or request shape |
| 401 | Missing or invalid credential | Check server configuration |
| 403 | Missing permission | Review the endpoint's required scopes |
| 404 | Resource unavailable to this organization | Check the ID and organization |
| 409 | Conflicting state | Read the resource and reconcile the action |
| 413 | Request exceeds the body limit | Reduce the payload below 25 MB |
| 422 | Validation failed | Correct the submitted values |
| 429 | Request limit reached | Respect retry-after |
| 500 | Unexpected server failure | Preserve diagnostics and assess safe recovery |
Keep the request ID
Responses include x-request-id. The error body also supplies a request ID. Log it with the endpoint, status and your own operation identifier. Keep participant content and the Authorization header out of general application logs.
A request ID helps investigate a call. It is not an idempotency key, a participant identifier or proof that an operation failed before making a change.
Separate transport failure from rejected requests
If a connection drops after you send a mutation, you may not know whether it succeeded. Do not blindly retry an invitation or check-in. Waiver submission supports a specific idempotency mechanism; other endpoints do not inherit that behavior.
For a failed read, a bounded retry may be appropriate. For a rejected write, first understand whether the response means the request was invalid, the current state forbids it or the outcome is uncertain. The recovery guide turns those cases into an integration checklist.