Metr Fit / API V1
Errors and recovery
Every API error includes a stable code, a readable message and a request ID.
Error shape
{
"error": {
"code": "no_suitable_size",
"message": "No available size is a reasonable match. Check the size chart or contact the store.",
"request_id": "req_example"
}
}HTTP status codes
| Status | Meaning / action |
|---|---|
| 400 | Malformed JSON, duplicate/unknown fields, or invalid query. Fix the request. |
| 401 | Missing, revoked or expired API key. |
| 403 | Key lacks the scope or is restricted to a different store. |
| 404 | Resource does not exist inside this tenant/store. |
| 405 | Wrong HTTP method; check Allow header. |
| 409 | Duplicate identifier, conflicting retry or invalid session transition. |
| 410 | Session expired; create a new one. |
| 413 / 415 | Body over 256 KiB / use application/json. |
| 422 | Invalid values, chart mismatch or sizing abstention. Show a chart fallback where appropriate. |
| 429 | Rate limited. Respect Retry-After; default is 300 requests/minute/key. |
| 500 / 503 | Internal/dependency failure. Retry safe operations with bounded backoff. |
Sizing-specific codes
- unsupported_product: this category is not supported.
- unverified_chart: attach and approve a chart first.
- no_available_sizes: no current variants match chart rows and chosen color.
- insufficient_evidence: provide a usual size, a size worn at another brand or a body measurement.
- invalid_answers: an answer is invalid or irrelevant for this product.
- no_suitable_size: the available sizes are too poor a match; do not force a size.
Safe retries
GET operations, identical recommendation/completion requests and identical event deliveries can be retried. Merchant/product/chart/session creation does not have automatic idempotency: reconcile state before retrying. Retry-After is returned for 429. Keep the request ID for support; never log API keys or body measurements.