Small contracts. Explicit meaning.
Reviewed domain conventions for money, request identity, idempotency and errors. Illustrative, not an executable API specification.
Repeat the request, not the operation.
For operations using the idempotency service, the key is scoped to an organization and operation. The same key and same canonical request replay the stored result. Reusing a key with a different request conflicts. Clients must preserve the key while resolving an uncertain submission.
Idempotency-Key: evaluation-order-0001
// Illustrative header only; no request is sent.
// Current service format: 8–128 characters,
// letters, digits, underscore, period, colon or hyphen.Errors carry a reason and a request identity.
The core error format includes an error code, message and requestId. Use the request identity when discussing a redacted failure with an approved support contact. Do not share bearer credentials, customer records or raw provider responses.
{
"error": {
"code": "capability_disabled",
"message": "This operation is not enabled",
"requestId": "synthetic-request-reference"
}
}| HTTP | Core meaning |
|---|---|
| 400 | Invalid request. |
| 401 / 403 | Authentication required / authority denied. |
| 404 | Unavailable record within the authorized scope. |
| 409 | Idempotency conflict or invalid state transition. |
| 422 | Asset, environment, quote or capability constraints. |
| 429 / 503 | Rate limit / provider or service unavailable. |
Confirm the exact endpoint contract.
Not every application route has identical headers, rate limits or response behavior. These conventions explain the domain, not a universal transport guarantee. Pagination, retry policy, version support and exact schemas must be reviewed for the approved endpoint set.