Idempotency And Errors

Order creation is idempotent by the resolved type source and externalOrderId. Also send a stable Idempotency-Key for each external order:

Idempotency-Key: talabat-TLB-84721

Keep the key at 200 characters or fewer.

Safe Retry

When Plato receives the same order identity again, it returns the original order with 200 OK:

{
  "data": {
    "id": "cm_order_123",
    "externalOrderId": "TLB-84721",
    "appSlug": "talabat",
    "type": "PICK_UP",
    "referenceNumber": 1043,
    "status": "PENDING",
    "paymentStatus": "PAID",
    "total": 65,
    "currency": "AED",
    "createdAt": "2026-07-28T12:30:03.120Z"
  },
  "meta": {
    "idempotentReplay": true,
    "requestId": "my-trace-84721"
  }
}

Retry network timeouts and 500 responses with the same externalOrderId and Idempotency-Key.

Existing Orders

When an order already exists, Plato returns the stored order instead of creating another one. Generate a new external order id only for a genuinely new order.

Validation Error

Invalid fields and inconsistent totals return 422 Unprocessable Entity with field paths:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The order payload failed validation",
    "details": [
      {
        "path": "pricing.subtotal",
        "message": "pricing.subtotal must equal the sum of item totals"
      }
    ]
  },
  "requestId": "my-trace-84721"
}

Endpoint Status Codes

If an aggregator value in type does not belong to an app installed in the API key workspace, Plato does not create or update an order:

{
  "error": {
    "code": "AGGREGATOR_APP_NOT_INSTALLED",
    "message": "Aggregator app 'talabat' is not installed in this workspace",
    "details": {
      "appSlug": "talabat"
    }
  },
  "requestId": "my-trace-84721"
}

Status	Code	Action
`201`	—	New order created. Store the Plato `data.id`.
`200`	—	Existing order returned for a safe retry.
`400`	`INVALID_JSON`	Fix malformed JSON or the idempotency key.
`401`	`MISSING_API_KEY`, `INVALID_API_KEY`	Supply or rotate the API key.
`403`	`INSUFFICIENT_PERMISSION`	Add `restaurant:order:create` to the API key role.
`409`	`AGGREGATOR_APP_NOT_INSTALLED`	Install the selected aggregator app in the API key workspace.
`413`	`PAYLOAD_TOO_LARGE`	Keep the JSON body at or below 1 MB.
`415`	`UNSUPPORTED_MEDIA_TYPE`	Send `Content-Type: application/json`.
`422`	`VALIDATION_ERROR`	Correct the named fields.
`500`	`INTERNAL_ERROR`	Retry with exponential backoff and the same idempotency values.

Recommended Backoff

For a timeout or 500, retry after approximately 1, 2, 5, 10, and 30 seconds. Stop after a bounded number of attempts and place the order in a reconciliation queue. Log the X-Request-Id, external order id, HTTP status, and Plato order id. Do not log the API key or the full customer payload.

Start

CMS

Connect360

Restaurant

Aggregator Integration

Forms

Idempotency And Errors

Safe Retry

Existing Orders

Validation Error

Endpoint Status Codes

Recommended Backoff

​Safe Retry

​Existing Orders

​Validation Error

​Endpoint Status Codes

​Recommended Backoff

Safe Retry

Existing Orders

Validation Error

Endpoint Status Codes

Recommended Backoff