Errors
The error envelope, every error code, and what to do about each.
Every error response has the same shape:
{
"error": {
"type": "invalid_request_error",
"code": "photo_required_for_channel",
"message": "Product 66a1… has no images: channel \"etsy\" requires at least one image. Add an image, then publish again.",
"param": null,
"doc_url": "https://developers.nembol.com/docs/getting-started/errors#photo_required_for_channel"
},
"request_id": "req_9f83…"
}type— one of four families (below). Branch on this for retry logic.code— stable machine-readable string. Branch on this for specific handling.message— human-readable, English, tells you how to fix it. Never parse it.param— the offending field for validation errors (e.g.variants[2].price).request_id— include it when contacting support.
Error types
type | HTTP | Retry? |
|---|---|---|
invalid_request_error | 400, 404, 409, 412, 422 | No — fix the request |
authentication_error | 401, 403 | No — fix key or scopes |
rate_limit_error | 429 | Yes — after Retry-After seconds |
api_error | 5xx | Yes — with exponential backoff |
Common codes
| Code | HTTP | Meaning |
|---|---|---|
invalid_api_key | 401 | Key missing, malformed, revoked or rolled |
insufficient_scope | 403 | Key lacks the scope for this endpoint |
plan_not_eligible | 403 | Store's plan does not include API access |
product_not_found / order_not_found / … | 404 | No such resource in this store |
validation_failed | 422 | See param and message |
photo_required_for_channel | 422 | Publishing an imageless product to a channel that requires images |
channel_not_connected | 422 | Publish/delist on a channel the store hasn't connected |
sku_not_found / sku_ambiguous | 422 | Batch inventory item rejected (unknown or duplicated SKU) |
idempotency_key_reused | 409 | Same Idempotency-Key with a different payload |
precondition_failed | 412 | expected_updated_at didn't match — re-read and retry |
rate_limit_exceeded | 429 | Bucket empty — honor Retry-After |
write_quota_exceeded | 429 | Daily channel-write quota reached |
Codes are added over time; handle unknown codes by falling back on type.
Need help?
The API is in private beta — email us and a human replies, usually within one business day.