Error codes and token expiration

Error response structure

All error responses from EcartAPI follow this format:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "...",
  "ecartapiError": false
}

Field	Description
`statusCode`	HTTP status code.
`error`	Short error label.
`message`	Human-readable description of the error.
`ecartapiError`	`true` = EcartAPI internal error (not your fault). `false` = the platform rejected the request.

See Billing and request counting for how ecartapiError affects billing.

Common status codes

Code	Cause	Action
`400 Bad Request`	Invalid or missing fields in the request body. `ecartapiError: false`.	Check the `message` field for which parameter is wrong.
`401 Unauthorized`	The store access token is invalid or expired. `ecartapiError: false`.	Prompt the store owner to reconnect (see below).
`403 Forbidden`	The token is valid but the app lacks permission for this resource on this platform.	Check platform-level permissions in your developer portal.
`404 Not Found`	The requested resource does not exist on the platform (e.g. order was deleted).	Do not retry; the resource is gone.
`422 Unprocessable Entity`	The request was understood but the platform rejected the data (e.g. invalid carrier, mismatched field values).	Check the response body for platform-specific details.
`429 Too Many Requests`	The connected platform is rate-limiting requests. EcartAPI never generates 429 itself.	Back off and retry. See Limits.
`503 Service Unavailable`	The ecommerce platform's API is temporarily down. `ecartapiError: false`.	Retry with exponential backoff.

Detecting and handling expired tokens

Store access tokens can expire or be revoked by the platform at any time — the store owner may uninstall the app, or the platform may rotate tokens on a schedule.

Signal: A 401 response with ecartapiError: false means the platform rejected the token. The token is no longer valid.

Action: You cannot refresh the token programmatically. The store owner must go through the OAuth flow again to issue a new token. Your system should:

Mark the store as disconnected.
Notify the store owner that reconnection is needed (e.g. email, dashboard alert).
Direct them to your OAuth URL to reconnect.
On the redirect callback, update the stored access_token — the shop_id will be the same.

Platform-specific token behavior

Etsy

Etsy access tokens are short-lived (~1 hour). EcartAPI automatically uses the refreshToken to obtain a new access token — you do not need to manage this yourself.

However, Etsy refresh tokens expire after 90 days of inactivity. If a store has had no API activity for 90 days, the refresh token becomes invalid and cannot be used to get a new access token. The store owner must reconnect.

Signs of an expired Etsy refresh token: 401 errors with ecartapiError: false that persist across retries, typically for stores that have been inactive for several months.

eBay

eBay tokens have a fixed expiration (typically 18 months). EcartAPI handles refresh automatically. A 401 with ecartapiError: false on an eBay store usually means the token was revoked — the store owner uninstalled the app or eBay revoked it for policy reasons.

Amazon

Amazon tokens do not expire in the traditional sense, but if the store owner removes the EcartAPI app from their Amazon Seller Central, all requests will return 401. The store owner must reconnect and re-authorize.

Distinguishing platform errors from integration errors

401 + ecartapiError: false  →  Token expired or revoked. Reconnect the store.
503 + ecartapiError: false  →  Platform is down. Retry later.
400 + ecartapiError: false  →  Your request payload has an error. Fix it.
5xx + ecartapiError: true   →  EcartAPI infrastructure error. Retry; not billable.

→ Store identification — How to detect reconnection and update the token.
→ Limits — Platform-level rate limiting (429 behavior).
→ Billing and request counting — How ecartapiError affects your monthly quota.