Errors
The API uses a stable JSON error envelope.
{
"success": false,
"error": {
"code": "validation_error",
"message": "The products field is required.",
"details": {}
},
"meta": {
"api_version": "2026-04"
}
}Common Status Codes
| Status | Meaning |
|---|---|
200 | Request succeeded. |
201 | Resource or batch operation was accepted/created. |
400 | API version is missing from a dated API request. |
401 | Missing, invalid, or disabled API key. |
403 | Protection rule, missing scope, or connection unavailable when writing. |
404 | Resource or API version not found. |
405 | HTTP method not allowed for the endpoint. |
409 | The request conflicts with state the API already recorded. |
422 | Request was valid JSON but failed validation. |
429 | Rate limit exceeded. |
500 | Unexpected Revi-side error. |
503 | Temporary maintenance window. See Maintenance Windows. |
Common Error Codes
| Code | When it appears |
|---|---|
authentication_required | The X-API-KEY header is missing. |
invalid_api_key | The API key is unknown or disabled. |
invalid_version | The dated API version does not exist. |
version_sunset | The requested dated version has been retired. |
validation_error | A field, filter, enum, or payload shape is invalid. |
not_found | The requested resource does not exist for the API key context. |
method_not_allowed | The path exists but does not support the HTTP method. |
server_error | An unexpected server-side error occurred. |
version_unavailable | The dated API version exists but is not enabled for this environment. |
invalid_token | The Bearer credential is missing, malformed, expired, or revoked. |
insufficient_scope | The API client does not hold the scope the operation requires. |
connection_not_found | The connection does not exist, is inactive, belongs to another store, or is not granted to the client. |
connection_unavailable | In 2026-04, a product or order-product write found that its connection was disabled, retired or removed after authentication. |
owner_rejected | An order source update was rejected; this includes a connection becoming unavailable during the request. Check the connection before retrying. |
For bulk orders in 2026-04, a connection becoming unavailable is reported in each failed item's results[].error. If no order is processed, the request returns 422 validation_error. Successful items are not rolled back. Check item results and the connection state before retrying.
Revision and Idempotency Conflicts
The order source and backfill operations are ordered and idempotent: every write carries a revision, an event ID, or an idempotency key. When a write contradicts what the API already recorded under the same identifier, it is rejected with 409 instead of overwriting the stored state.
| Code | When it appears |
|---|---|
stale_catalog_revision | The catalog_revision sent is lower than the revision already stored for the connection. |
catalog_revision_payload_conflict | The catalog_revision was already recorded with a different status catalog. Resending it with the identical catalog deduplicates instead. |
stale_source_revision | The order revision sent is lower than or equal to the revision already stored for that order, under a new event_id. |
source_event_payload_conflict | The event_id was already recorded with different content. Resending it with the identical content deduplicates instead. |
idempotency_payload_conflict | The Idempotency-Key was already used for a backfill with a different request payload. |
How a client should react
- A
409is never resolved by retrying the same request with the same content and expecting a different result. Retrying an identical request after a timeout is safe and returns the stored outcome, so it is not a conflict. - Treat a stale revision as "another writer is ahead of me". Re-read the current state, then send the next transition with a strictly higher revision. Do not decrement or reset a revision counter to force a write through.
- Treat a payload conflict as a client bug: the same identifier was reused for different content. Fix the identifier — generate a new
event_idorIdempotency-Keyfor genuinely new content — rather than mutating the content behind an identifier that was already accepted. - Never resend a backfill under a new
Idempotency-Keyjust to escape a conflict; that can duplicate work. Confirm what the previous key recorded first. - Do not retry
409in a loop or with backoff. It is a deterministic outcome and will keep failing until the revision or the identifier changes.
Other Conflicts
| Code | When it appears |
|---|---|
recipient_optout_revocation_requires_review | A business tried to revoke a recipient opt-out through the API. This is never granted automatically; documented renewed consent and Support review are required. |
This conflict is also deterministic. Do not retry it — contact Support with the renewed consent evidence instead.
Rate limit errors use the 429 response documented in Rate Limits and can omit the standard success envelope.
Maintenance Windows (503)
While a Revi service is being deployed, its API can answer 503 Service Unavailable for a short time, usually under a minute and rarely a few minutes. That response:
- comes with
Retry-After: 60and the headerX-Revi-Deploy-Gate: 1; - has an HTML body, not the JSON envelope, so do not parse it as an API error;
- means the request was not processed.
Retry the same request after the Retry-After delay, with exponential backoff and jitter, for at least 15 minutes before giving up. Keep failed writes in your own queue instead of dropping them. Retrying is safe: for the 2026-10 order source and backfill operations, resend with the same revision, event_id or Idempotency-Key, and an identical retry returns the stored outcome instead of creating a duplicate.
Recommended Client Handling
- Treat
success: falseas failure even if the HTTP status is200. - Check
Retry-Afteron429and503. - Log
error.codefor API requests. - Redact API keys and customer email addresses from logs.