Errors

Check the HTTP status before reading an answer. A failed request returns no output.

Every response, including an error, has an X-Blatent-Request-ID header. Include it when you contact support.

Error bodies

Most errors use an error object:

{
  "error": {
    "code": "SCHEMA_NOT_FOUND",
    "message": "Schema version not found",
    "path": "",
    "request_id": "0b9f6c2e-4d1a-4f3b-9a57-2c8e1d6b7f40"
  }
}

Branch on code, not message. path is a JSON Pointer to the failing schema or output location, or "" when there is none. request_id equals the X-Blatent-Request-ID header. There is no retryable field; the tables below say which failures to retry.

Two failures use detail instead:

401: a missing or invalid API key returns this body with the WWW-Authenticate: Bearer header:

{"detail":"Missing or invalid API key"}

Check the key and its Bearer header before retrying.

422 request validation: a body that does not match the request format returns a detail list. Each item has loc (where the problem is), msg and type. For example, sending neither schema nor schema_id returns {"detail":[{"loc":["body"],"msg":"Provide exactly one of schema or schema_id.","type":"value_error"}]}.

Other 422 responses use the error object: the request was well formed but cannot run. Check for detail before reading error.code. A 403 from the edge firewall has no JSON body.

Request, schema and reference errors

Status	Code	Meaning	Retry
404	NOT_FOUND	Unknown route.	No
405	METHOD_NOT_ALLOWED	Known route, wrong method. The Allow header lists the methods.	No
404	SCHEMA_NOT_FOUND, POLICY_NOT_FOUND	The reference does not exist for your key.	No
409	VERSION_CONFLICT	The version or alias holds other content. Nothing changed.	Read the current version first
413	REQUEST_TOO_LARGE	The body is over its size limit, or the request needs more work than one request may use.	No
422	SCHEMA_INVALID, SCHEMA_UNSUPPORTED, UNSUPPORTED_RUNTIME	The schema is invalid or uses an unsupported feature. path points to it.	No
422	UNSATISFIABLE_SCHEMA, UNSATISFIABLE_CONTEXT, NO_VALID_TRANSITION	No output can satisfy the schema with this input and context.	No
422	CONTEXT_INVALID, CONTEXT_TOO_LARGE	The input, state, parameters or user context fail the schema's request rules, or are too large.	No
422	CONSTRAINT_BUDGET_EXCEEDED	The schema needs more constrained decisions or validation time than one request allows. Long outputs and costly schema checks, such as complex patterns over many values, can reach it.	No
422	CONSTRAINT_SEARCH_EXHAUSTED	No schema-compliant output was found within the execution budget. This is not proof that none exists.	A simpler schema or task may succeed
422	STATE_EFFECT_INVALID, OUTPUT_VALIDATION_FAILED	The result failed the schema's state or output checks. No output is returned.	No
422	INVALID_REQUEST	The service rejected the request, for example an invalid X-Blatent-Retry-Count header.	No

Policy errors

Status	Code	Meaning	Retry
403	POLICY_DENIED	The policy denied every candidate.	No
422	POLICY_SEARCH_EXHAUSTED	No allowed output was found within policy_max_retries. This is not proof that none exists.	A larger policy_max_retries may succeed
422	POLICY_INVALID, POLICY_REJECTED, POLICY_EXECUTION_FAILED, POLICY_FEEDBACK_UNAVAILABLE, POLICY_FEEDBACK_BOUNDARY_UNAVAILABLE, POLICY_PLAN_INVALID, POLICY_PLAN_CAPACITY, POLICY_PLAN_UNSATISFIABLE	The policy, its feedback mode or its plan cannot be used for this request.	No
429	POLICY_CAPACITY_BUSY	The policy engine is busy.	Yes, after a short pause
503	POLICY_UNAVAILABLE, POLICY_CAPABILITY_UNAVAILABLE	Policy evaluation is unavailable or failed inside the service, not because of your policy.	Yes, later

Policy failures never return a rejected candidate as output.

Account and limit errors

Status	Code	Meaning	Retry
403	BUDGET_EXHAUSTED	The remaining balance cannot cover the request's maximum cost.	No
403	PREVIEW_UNAVAILABLE	Inference is not enabled for this key's account.	No
403	SCHEMA_LIMIT_REACHED	This key has saved as many schema and policy versions as allowed. Nothing was saved.	No
429	RATE_LIMITED	Your account reached its request or token rate limit, or your network sent too many requests.	Yes, after Retry-After
429	CONCURRENCY_LIMITED	Your account already has as many requests running as its limit allows.	Yes, after Retry-After (1 second)

Service errors

Status	Code	Meaning	Retry
409	OUTCOME_INDETERMINATE	The request may have run, but no result came back. Also returned when a request carries an X-Blatent-Retry-Count above 0.	Never automatically. Read a registration or alias back before trying again
409	RUNTIME_CONTRACT_ERROR	The service produced a result it could not verify. No output is returned.	No
500	INTERNAL_ERROR	Unexpected failure.	Not automatically
503	RUNTIME_UNAVAILABLE	The service was unavailable before the request started.	Yes, after Retry-After
503	GPU_CAPABILITY_UNAVAILABLE	A model capability the request needs, such as schema checking, is unavailable or failed inside the service.	Yes, later
529	CAPACITY_BUSY	Capacity is full. On a registration, inspection or alias, another schema is compiling.	Yes, after Retry-After
504	CAPACITY_BUSY	The request deadline passed. Execution may already have started; no output is returned.	Yes, within a bounded retry budget

The service may add codes. Keep unknown codes and the request ID for diagnostics.

Follow the retry guide rather than retrying all failures the same way.