Errors

All errors have the same shape. Program against code, which doesn’t change; message is for whoever reads the log.

{
  "error": {
    "code": "validation_failed",
    "message": "The request body is not valid.",
    "details": [{ "field": "order.shopify_order_id", "message": "Required: an Order gid or its numeric id." }]
  }
}

Authentication

Code	HTTP	What happened	What to do
missing_api_key	401	Authorization is missing.	Send Bearer rvw_live_….
invalid_api_key	401	The key doesn’t exist, was revoked or the store uninstalled the app.	Create another one in Channels.
missing_signature	401	X-Signature or X-Timestamp is missing.	See the signature.
timestamp_out_of_range	401	X-Timestamp isn’t in seconds or is more than 5 minutes off.	Sync your clock (NTP).
invalid_signature	401	The signature doesn’t match.	Sign the exact body you send, with that key’s secret.
insufficient_scope	403	The key doesn’t have the permission. details says which one is needed.	Use a key with a wider scope.
plan_required	403	The API is part of the Pro plan.	Change plans from the app.
rate_limited	429	More than 120 requests in a minute.	Wait as long as Retry-After says.

The request

Code	HTTP	What happened
invalid_json	400	The body isn’t JSON.
validation_failed	422	A field isn’t valid. details lists each field with its error. With 413, the body went over the maximum size.
method_not_allowed	405	That path doesn’t accept that method.
idempotency_key_reused	422	The Idempotency-Key was already used with a different body.
idempotency_in_progress	409	Another request with the same Idempotency-Key is still in progress. Retry in a moment.

Orders and requests

Code	HTTP	What happened
not_found	404	Nothing with that id in this store.
order_not_found	404	Shopify doesn’t return that order in this store. Check the id.
order_cancelled	422	The order is cancelled.
no_reviewable_products	422	The order has no products to review.
request_closed	409	The request was already answered, expired or cancelled. details.status says which.
invalid_state	409	The change isn’t possible in the current state (for example, sending now one that was already sent).

Reviews

Code	HTTP	What happened
product_not_found	422	No product in the store matches. A SKU repeated across two products also returns this error.
product_not_in_order	422	The product isn’t in that order.
review_exists	409	That order already has a review for that product. details includes its id.
duplicate_in_batch	—	Only in bulk import: the same review appears earlier in the batch.

Server

Code	HTTP	What to do
shop_unavailable	503	The store doesn’t have an active session with the app. Retry later.
internal_error	500	An error on our side. Retry; if it keeps happening, write to us at contacto@leadit.tech.