Ongapi returns JSON errors. Retry only when the status says the request can succeed later.
| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid request body or headers | Fix the payload. Write routes document required fields in Orders and events |
| 401 | Missing or revoked API key | Create a new key and update the caller |
403 plan_limit_exceeded | Live connection or order cap | Upgrade the plan or wait for the next period |
| 404 | Unknown id, or a key from another account | Check the id. Do not probe other tenants |
409 waybill_unavailable | No platform AWB yet (or Shopify label unsupported) | See Orders and events |
| 429 | Rate limit for this API key | 60 requests per second per key. Honor Retry-After, then back off |
501 capability_unsupported | Missing partner scopes or unsupported ship mode | Re-authorize the shop after scopes are added |
502 platform_error | Marketplace API error | Read error.message; retry only if the platform issue is transient |
Write APIs (POST …/ship, GET …/shipping-label, warehouses, inventory) use the same envelope. Full codes and platform notes: Orders and events.
Sandbox event logs are kept for 24 hours. Paid plans keep them longer (Starter 7 days, Growth 14 days, Scale 30 days). Disconnecting a shop stops new ingest for that connection. Order reads stay available when outbound webhooks are paused for a plan limit.
Exact response fields are in the API reference.