Error response format, status codes and when to retry.
Error responses are JSON with status, code, title, detail, data, instance (the request path and query string) and timestamp. data is {}, or a message string on some validation errors; do not branch on it. Branch on code, and on errors[].errorCode for validation errors.
Most 400 responses have code ERROR_VALIDATION and list each problem in errors:
- When the request does not match the schema, each item has
path(for example/body/email) and anerrorCodeending in.openapi.validation. - Other problems have
location(for exampleresource.envelope) and a specificerrorCode, such asENVELOPE_ALREADY_PUBLISHED.
Some ERROR_VALIDATION responses have no errors: for example a body that is not valid JSON. Malformed IDs and unknown query parameters also cause 400. Unknown fields in the request body are removed without an error, so a misspelled field is ignored.
| Status | code | When |
|---|---|---|
| 400 | ERROR_VALIDATION | The request is invalid or the resource is in the wrong state. See errors. |
| 400 | ERROR_ENVELOPE_PUBLISHED | You upload a file or add a signer to an envelope that is published and cannot take it. No errors. |
| 401 | ERROR_UNAUTHORIZED | The x-resly-api-key header is missing, is not 64 characters, or is unknown. |
| 402 | ERROR_PAYMENT_REQUIRED | The team is on a free plan and its e-sign limit is reached. Only returned when publishing: Publish Envelope, Create and Publish Envelope, or Submit Form when the form publishes. Upgrade the plan. |
| 403 | ERROR_FORBIDDEN | The API key's user is not allowed to do this on the resource, or the operation is not allowed on this kind of resource (for example publishing a template). |
| 404 | ERROR_*_NOT_FOUND | The envelope, participant, file or form does not exist. A path under /v2 that does not exist returns ERROR_ENDPOINT_NOT_FOUND. |
| 413 | ERROR_PAYLOAD_TOO_LARGE | A file or the whole request body is larger than 50 MB. No errors. |
| 405 | ERROR_METHOD_NOT_ALLOWED | Unsupported request method on the path, for example POST instead of GET. The allow response header lists the supported methods. |
| 415 | ERROR_UNSUPPORTED_MEDIA_TYPE | The payload format is not supported. Set the content-type header to application/json, except for file uploads, which use multipart/form-data. |
| 429 | varies | Too many requests. Wait the number of seconds in the retry-after response header before retrying. Read header names case-insensitively. |
| 500 | ERROR_GENERIC | Something failed on our side. Retry as described below, and if it persists, contact [email protected] with the timestamp and instance from the response. |
Retrying safely
Retry GET requests on network errors, timeouts, 429 and 5xx responses with exponential backoff. For POST, check the state first (below). Do not retry other 4xx responses unchanged.
POST requests are not idempotent: one that timed out or returned 5xx may still have taken effect. Check the result with Get Envelope or List Envelopes before sending it again. Publish Envelope is safe to retry: if the first call succeeded, the retry returns 400 ENVELOPE_ALREADY_PUBLISHED.