Skip to content

Errors ​

The API uses a stable JSON error envelope.

json
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "The products field is required.",
    "details": {}
  },
  "meta": {
    "api_version": "2026-04"
  }
}

Common Status Codes ​

StatusMeaning
200Request succeeded.
201Resource or batch operation was accepted/created.
400API version is missing from a dated API request.
401Missing, invalid, or disabled API key.
403Protection rule, missing scope, or connection unavailable when writing.
404Resource or API version not found.
405HTTP method not allowed for the endpoint.
409The request conflicts with state the API already recorded.
422Request was valid JSON but failed validation.
429Rate limit exceeded.
500Unexpected Revi-side error.
503Temporary maintenance window. See Maintenance Windows.

Common Error Codes ​

CodeWhen it appears
authentication_requiredThe X-API-KEY header is missing.
invalid_api_keyThe API key is unknown or disabled.
invalid_versionThe dated API version does not exist.
version_sunsetThe requested dated version has been retired.
validation_errorA field, filter, enum, or payload shape is invalid.
not_foundThe requested resource does not exist for the API key context.
method_not_allowedThe path exists but does not support the HTTP method.
server_errorAn unexpected server-side error occurred.
version_unavailableThe dated API version exists but is not enabled for this environment.
invalid_tokenThe Bearer credential is missing, malformed, expired, or revoked.
insufficient_scopeThe API client does not hold the scope the operation requires.
connection_not_foundThe connection does not exist, is inactive, belongs to another store, or is not granted to the client.
connection_unavailableIn 2026-04, a product or order-product write found that its connection was disabled, retired or removed after authentication.
owner_rejectedAn 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.

CodeWhen it appears
stale_catalog_revisionThe catalog_revision sent is lower than the revision already stored for the connection.
catalog_revision_payload_conflictThe catalog_revision was already recorded with a different status catalog. Resending it with the identical catalog deduplicates instead.
stale_source_revisionThe order revision sent is lower than or equal to the revision already stored for that order, under a new event_id.
source_event_payload_conflictThe event_id was already recorded with different content. Resending it with the identical content deduplicates instead.
idempotency_payload_conflictThe Idempotency-Key was already used for a backfill with a different request payload.

How a client should react ​

  • A 409 is 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_id or Idempotency-Key for genuinely new content — rather than mutating the content behind an identifier that was already accepted.
  • Never resend a backfill under a new Idempotency-Key just to escape a conflict; that can duplicate work. Confirm what the previous key recorded first.
  • Do not retry 409 in a loop or with backoff. It is a deterministic outcome and will keep failing until the revision or the identifier changes.

Other Conflicts ​

CodeWhen it appears
recipient_optout_revocation_requires_reviewA 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: 60 and the header X-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.

  • Treat success: false as failure even if the HTTP status is 200.
  • Check Retry-After on 429 and 503.
  • Log error.code for API requests.
  • Redact API keys and customer email addresses from logs.

Public API documentation for Revi.