Errors
Errors are returned as JSON. Most responses use an error code string; many also include a human-readable message. Validation failures may include field-level details.
Common shape
{
"error": "validation_error",
"message": "Invalid request body.",
"details": {
"percentile": ["Number must be greater than or equal to 1"]
}
}
Status codes
| Status | Typical error | When |
|---|---|---|
400 | validation_error | Invalid JSON or schema |
400 | unknown_measurement | Measurement name not recognized |
400 | unknown_clothing / unknown_posture | Invalid clothing or posture id |
401 | string message | Missing or invalid API key |
402 | free_tier_exhausted | Free tier used up and no paid credits |
402 | insufficient_credits | Account has no credits available |
402 | insufficient_predictions | Batch needs more predictions than available |
404 | model_not_found | No model for that measurement + gender |
422 | gender_not_supported | Measurement does not support the gender |
422 | value_below_percentile_range | Lookup value below P1 |
422 | value_above_percentile_range | Lookup value above P99 |
429 | rate_limit_exceeded | More than 120 requests / 60s per key |
500 | inference_error / internal_error | Unexpected server failure |
Rate limits
Authenticated traffic is limited to 120 requests per 60-second window per API key.
Examples
Free tier exhausted
{
"error": "free_tier_exhausted",
"message": "Free tier limit reached (10 calls per 24 hours). Resets in 3 hours. Purchase credits to continue immediately.",
"resets_at": "2026-07-18T02:00:00.000Z"
}
Batch needs more predictions
{
"error": "insufficient_predictions",
"message": "This request requires 5 predictions but only 2 free-tier calls are available.",
"requested_predictions": 5,
"available_predictions": 2,
"billing_mode": "free",
"resets_at": "2026-07-18T02:00:00.000Z"
}
Value outside percentile range
{
"error": "value_below_percentile_range",
"message": "The provided value is below the 1st percentile for this measurement, gender, age, and country.",
"measurement": "Stature",
"value": 1200,
"unit": "mm"
}
Failed validation and out-of-range lookups do not consume credits or free-tier calls. See Credits.