ZAYUNO / DOCSPortalda ochish ↗AI agent index ↗

Errors & Idempotency

Explicit failures and persistent idempotency prevent duplicate transactions when clients, agents or networks retry.

Error contract

Use the ErrorResponse schema in OpenAPI. Provider and Core errors may have different HTTP wrappers; do not assume a generic NestJS error object is an RFC 7807 problem response.

Return a safe, actionable message and the appropriate code. Do not expose secrets, full customer data or internal stack traces.

Delivery failures

CodeMeaningNext step
DELIVERY_OUT_OF_AREAVerified coordinates lie outside the selected restaurant delivery areaAsk for another address or restaurant
DELIVERY_COVERAGE_NOT_CONFIGUREDDelivery coverage is missing or invalidRestaurant operator must configure coverage
DELIVERY_CONDITIONS_NOT_METProvider rejected branch delivery conditions without proving a geographic causeCheck minimum amount, hours and address; do not guess the reason

These are non-retryable with unchanged inputs. They retain the same code through REST and MCP. Inventory failures still use RESOURCE_UNAVAILABLE; delivery rejection must not be presented as an item being out of stock.

Action idempotency

Every create-action request carries an idempotencyKey.

  1. Store the key and associated action durably with a unique database constraint.
  2. Make duplicate detection and order creation atomic.
  3. A retry with the same key returns the existing action instead of creating or charging again.
  4. An incompatible payload for an already used key must not silently mutate the original order.
  5. Keep the behavior across process restarts and concurrent requests.

An in-memory map or cache alone is not sufficient for production order idempotency.

Retry decisions

SituationNext step
Validation failureFix the request; do not retry unchanged
Invalid authenticationFix credentials or signature direction
Expired quoteObtain a fresh quote and confirmation
Unknown result after timeoutQuery status or retry the same idempotency key
Temporary upstream failureBounded backoff; preserve request identity
State conflictInspect existing action before another mutation

HTTP status varies by route and failure. Read the structured code and validation report as well as the status. See troubleshooting.

Tests before certification

Send concurrent duplicates, retry after a simulated timeout, restart the backend and resend a key. Verify one provider order exists and the same action ID is returned. Check cancellation and webhook duplicates separately.