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
GETrequests are safe to retry.- Do not retry a
POSTblindly 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.
Need help with an integration? Contact support.