Errors
Errors use application/problem+json and include a stable machine-readable
code plus a request identifier for support and debugging.
{
"type": "https://modaic.dev/problems/validation-error",
"title": "Unprocessable Content",
"status": 422,
"detail": "The request did not match the expected schema.",
"code": "validation_error",
"requestId": "b80926a9-e5c6-4bc7-a5c5-0ef284bf6457",
"details": []
}
Status codes
| Status | Meaning |
|---|---|
400 | The request is invalid outside normal schema validation. |
401 | Authentication is missing, invalid, or revoked. |
403 | The caller lacks a required scope or resource role. |
404 | The route or an accessible resource was not found. |
409 | The request conflicts with current state or reuses an idempotency key for a different payload. |
415 | The request content type is unsupported. |
422 | A path, query, header, body, or provider response failed validation. |
429 | The caller exceeded a rate limit. |
500, 502, 503 | A server or upstream dependency failed. Retry only when safe. |
Idempotency
POST /v1/decision and its alias POST /v1/systemone accept an optional
Idempotency-Key header. Without it, each call is a new request, so retries
are not deduplicated.
POST /v1/models/{modelId}/batch-decisions and
POST /v1/models/{modelId}/alignments require the header. Whenever supplied,
the key must be between 8 and 255 characters.
Reuse the same key when retrying the same logical request. A completed response
is replayed. Reusing the key with a different
payload returns 409 idempotency_key_reused. A concurrent decision duplicate
may return 409 decision_in_progress; retry it with the same key after a short
delay.
Request identifiers
Every response exposes x-request-id. Send your own UUID in the
x-request-id request header to correlate a call with your logs, or let Modaic
generate one. Include this value when contacting support.