Errors and retries

One rule runs through both directions: retry a network failure or a 5xx, correct a 4xx. The exception is 429, which is a temporary limit and is retried.

When SKUU calls the store's API

Return HTTP 200 once the write is complete, with the required receipt fields from the reference. SKUU checks the status and the identifying values. A success message is optional and its wording is the store's; extra response fields are ignored. A different success status, a missing required field or an incorrect reference counts as a failure.

Errors carry a stable code. SKUU reads the code to tell an already shipped order apart from an idempotency conflict on POST /cancel; the message is for people.

{"error":{"code":"unknown_variant","message":"The supplied variant_id does not exist"}}

Status codes the store returns

Status	`code`	When
`400`	`invalid_request`	The body fails validation.
`401`	`unauthorized`	The bearer token or signature is missing or invalid.
`403`	`forbidden`	These credentials do not allow the action.
`404`	`unknown_variant`, `unknown_order`, `unknown_line`	The referenced resource does not exist.
`409`	`idempotency_conflict`	The same reference was used for different data.
`409`	`order_already_shipped`	`POST /cancel` cannot stop the order because a line shipped.
`429`	`rate_limited`	Include `Retry-After` in seconds.
`500`	`temporary_failure`	The operation could succeed later.

SKUU makes up to three attempts per call, with exponential backoff from one second and jitter, a 30-second timeout each, and honours Retry-After. Any other 4xx stops the attempt and alerts SKUU customer service.

What happens after a failed call

PUT /inventory is retried on later sync cycles until its receipt matches, including after a 404 or an invalid success response. POST /orders can resume on a later injection pass after a temporary failure; a permanent 4xx needs customer service. A failed tracking or return write needs customer service to resume it. An incomplete cancellation resumes when the same order.cancelled is delivered again.

When the store's platform calls SKUU

{"error":{"code":"invalid_request","message":"The event does not match the schema.","field":"data.shipping_cost"}}

Status codes SKUU returns

Status	Meaning	What to do
`200`	Handled, or a valid duplicate, older stock state or recognised echo.	Stop delivery retries.
`400`	The body is not a UTF-8 JSON object.	Correct the JSON.
`401`	The signature or the shop URL is wrong.	Correct the authentication or the URL.
`403` `capability_disabled`	The capability is not enabled for this store.	Confirm activation with SKUU first.
`404`	SKUU cannot find the order, line or variant.	Correct the ID, or complete the catalogue import first.
`409`	The event conflicts with data SKUU already holds.	Inspect the original event and correct the cause.
`409` `order_already_shipped`	A cancellation reached an order with a shipped line.	Stop retries; it becomes a return. See Cancellation.
`413`	The body exceeds 512 KiB.	Reduce optional text or contact SKUU.
`422`	The event name, fields, currency, timestamps, references or quantities are invalid.	Read `error.code` and `error.field`, then correct the event.
`5xx` or no response	Processing did not finish, or the outcome is uncertain.	Resend the identical bytes.

Make at least three delivery attempts over at least fifteen minutes, always with the same event_id and the same body bytes. After a permanent rejection, correct the cause and send a new event ID. For a variant SKUU does not know yet, send the current stock state once the catalogue import has completed: replaying the rejected event cannot apply it.

Every code SKUU returns

409 carries event_id_conflict, timestamp_conflict or quantity_exceeded. 404 carries unknown_variant, unknown_order or unknown_line. 422 carries invalid_request for schema problems, plus unknown_event, future_timestamp, unknown_location, invalid_order, invalid_fulfillment, partial_quantity and aggregate_out_of_range.

SKUU never echoes input values back in a validation error.

What makes a retry safe

Call	Identity	Rule
`GET /products`	Cursor	A repeated read is safe.
`inventory.updated`	`event_id`, variant and location	An exact replay never applies the source change twice. Older states are ignored.
`PUT /inventory`	Variant and location	Set the supplied absolute quantity.
`order.created`	`order_id`	The first accepted paid order is final. A replay does not amend it.
`POST /orders`	`external_ref`	Return the original order receipt.
`fulfillment.shipped`	Package identity and SKUU references	An exact replay can resume tracking delivery without storing another package.
`PUT /orders/{order_id}/tracking`	`external_ref`	Return the receipt without a second customer notification.
`order.cancelled`	Order and its current cancellation state	Stopped orders stay stopped. Unfinished cancellations resume.
`POST /cancel`	`external_ref`	Return the original cancellation receipt once the order is stopped.
`return.created`	`event_id` and raw body	An exact replay stores nothing twice.
`POST /returns`	`external_ref`	Return the original return receipt.

Never reuse an identity for different data, and never split one event to get under the size limit. A order.created carries the complete order and a fulfillment.shipped describes one real package. An accepted order that needs an address correction is a call to SKUU, not a new event ID.

The next page is Products.