Errors and rate limits

The error format the API returns, what each HTTP status means and how to handle rate limiting.

HTTP status codes

The API uses standard HTTP status codes.

| Status | Meaning | | --- | --- | | 200 | The request succeeded. | | 400 | The request is malformed or a parameter is invalid. | | 401 | The API key is missing, invalid or revoked. | | 403 | The key does not have permission for this request. | | 404 | The store or the resource does not exist. | | 409 | The request conflicts with existing data, for example creating a product with a SKU that already exists. | | 422 | The request is well formed but a value is not acceptable. | | 429 | Too many requests. Slow down and retry. | | 5xx | A problem on our side. Retry after a short delay. |

Error format

Errors return a JSON body with a machine-readable code, a human-readable message and the HTTP status in data.status:

{
  "code": "wafle_unauthorized",
  "message": "Missing API key",
  "data": { "status": 401 }
}

Use code in your program logic. Messages are meant for people and may change.

Rate limits

Requests are rate limited per client to keep the API fast for everyone. When you send requests too quickly, the API responds with HTTP 429 and may include a Retry-After header with the number of seconds to wait.

Recommendations:

  • Respect Retry-After. If it is missing, wait and retry with exponential backoff, for example 1, 2, 4 and 8 seconds, with a small random delay added.
  • Use list endpoints with filters and pagination instead of fetching every record repeatedly.
  • Use bulk endpoints when you change many items.
  • Cache data that changes rarely, such as your product catalog.

Retrying safely

  • GET requests are safe to retry.
  • Do not retry a POST blindly after a timeout, because the first attempt may have succeeded. Read the resource first to check, or use a unique SKU or reference so that duplicates are rejected with HTTP 409.

Getting help

If you receive errors you do not understand, contact support and include the time of the request, the store slug, the endpoint and the response body. Never include your API key.

Was this helpful?

Need help with an integration? Contact support.