Errors

Errors use one JSON shape for every status:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "…",
    "param": "end",
    "request_id": "req_01J…",
    "doc_url": "https://docs.trusttyped.com/errors#invalid_request"
  }
}

• type — a stable category (see the table).
• code — a stable machine-readable code; branch on this.
• message — human-readable; may change, do not parse it.
• param — the offending parameter, when relevant.
• request_id — quote this in support requests.

Status codes

Status	type	When
400	invalid_request_error	Well-formed JSON that cannot run: bad schema, unknown field, invalid parameter, malformed Idempotency-Key, Idempotency-Key with stream.
401	authentication_error	Missing, malformed, unknown, or revoked API key.
403	permission_error	The key is valid but not allowed for this operation.
404	not_found_error	Unknown path.
409	idempotency_error	Idempotency key reused with a different body, or a request with that key is still in progress.
413	request_too_large	Body exceeds the size limit.
429	rate_limit_error	Per-key rate limit or per-org concurrency limit.
500	api_error	Unexpected server error.
503	overloaded_error	Engine busy/unavailable, or usage data unavailable.
504	timeout_error	Engine did not finish in time.

Error codes

code	Status	Meaning	What to do
missing_api_key	401	No Authorization header.	Send Authorization: Bearer <key>.
invalid_authorization_header	401	Header was not Bearer <key>.	Use the Bearer scheme.
invalid_api_key	401	Key malformed, unknown, or revoked.	Check the key; create a new one if revoked.
permission_error	403	Key valid but not permitted (e.g. not project-scoped).	Use a project API key.
not_found	404	Path does not exist.	Check the URL.
method_not_allowed	405	Wrong HTTP method for the path.	Use the documented method.
invalid_json	400	Body is not valid JSON.	Send valid JSON.
invalid_request	400	A parameter or field is invalid (see param).	Fix the value named in param.
model_not_found	400	Unknown model.	List models with GET /v1/models.
schema_registry_unavailable	400	Registry schema reference used before release.	Send the schema inline as an object.
extraction_rejected	400	Engine rejected the input.	Read message; adjust input/schema.
idempotency_not_supported_for_stream	400	Idempotency-Key sent with stream: true.	Pick one or the other.
idempotency_key_reused	409	Key reused with a different body, or stored result unreadable.	Use a new key, or resend the original body.
idempotency_in_progress	409	Same key still processing.	Retry after Retry-After (2s).
request_too_large	413	Body over the limit.	Reduce size (e.g. image).
rate_limit_exceeded	429	> 60 requests/min for this key.	Back off per Retry-After.
concurrency_limit_exceeded	429	> 2 concurrent requests for this org.	Wait for a slot; retry after Retry-After.
engine_timeout	504	Engine exceeded the time budget.	Retry; simplify the schema or use streaming.
engine_unavailable	503	No healthy engine replica.	Retry after Retry-After (5s).
engine_error	500	Engine failed on this request.	Retry; contact support with request_id if it persists.
engine_stream_error	500 (as an error event after streaming starts)	Failure mid-stream.	Retry; the stream may have partial data.
usage_unavailable	503	Usage data temporarily unavailable.	Retry after Retry-After.
internal_error	500	Unexpected server error.	Retry; report with request_id.

Engine input errors map to 400

An engine-side rejection of the input is surfaced as a 400 invalid_request (or extraction_rejected), never as a 500 — a rejected input is a client error.

Streaming errors

Checks that can fail before the engine starts (auth, rate limit, validation) return a normal JSON 4xx/5xx. After the stream has started, a failure is sent as a final error event instead:

{"type":"error","error":{"type":"api_error","code":"engine_stream_error","message":"Engine gagal memproses request saat streaming. Coba lagi."}}

See Streaming.