The Sparqle API uses conventional HTTP status codes. 2xx means success, 4xx
means the request was rejected (usually something you can fix), and 5xx means
a problem on Sparqle’s side.
Status codes
| Code | Meaning |
|---|
200 / 201 | Success. |
400 | Validation error — a field is missing, malformed, or out of range. |
401 | Missing or invalid API key. |
403 | The key isn’t allowed to act on this locationId or order. |
404 | The order, label, or resource doesn’t exist. |
429 | Too many requests — you’ve hit the rate limit. |
500 | Unexpected error on Sparqle’s side. |
Validation errors
Request bodies are validated field by field. A 400 response lists what failed,
so you can surface the specific problem:
{
"statusCode": 400,
"message": [
"deliveryName should not be empty",
"deliveryAddress.postalCode must be a string"
],
"error": "Bad Request"
}
- Missing a required field (
locationId)
Rate limits
Public tracking endpoints are throttled. If you exceed the limit you’ll get a
429 — back off and retry with exponential delay. If you expect sustained high
volume on the order endpoints, coordinate limits with your Sparqle contact.
Build retries with exponential backoff for 429 and 5xx responses, and
treat 4xx (except 429) as permanent — retrying won’t help until you fix the
request.
