Source: docs/integration/errors.md

API errors

The Public API uses JSON errors. The OpenAPI contract is authoritative for the

status and shape of each route.

Most Public API routes return:

{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED"
}

The HTTP channel returns a structured error object:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid JSON body"
  }
}

Recovery guide

Status	Typical codes	Recovery
`400`	`VALIDATION_ERROR`, `INVALID_CREDENTIAL`, `MANIFEST_INVALID`	Fix the request using the OpenAPI schema; do not retry unchanged input.
`401`	`UNAUTHORIZED`	Confirm the API key and base URL belong to the same environment; ask the administrator to reissue the bundle if needed.
`404`	`CAPABILITY_NOT_FOUND`	Confirm the capability ID belongs to the current access bundle.
`405`	`METHOD_NOT_ALLOWED`	Use the method documented for the route.
`409`	`CONFLICT`, `CONTRACT_TEST_REQUIRED`, `CREDENTIAL_NOT_CONFIGURED`	Resolve the current capability state, then retry the logical operation.
`413`	`REQUEST_TOO_LARGE`	Reduce the credential request to the documented limit.
`422`	`VALIDATION_ERROR`	Send a text message with a non-empty body and valid fields.
`500`	`AGENT_RUNTIME_ERROR`, `INTERNAL_ERROR`	Apply the host application's retry policy and retain the response code for support.
`503`	`CREDENTIAL_VAULT_UNAVAILABLE`	Do not rotate repeatedly; retry according to the host policy and contact the operator if it persists.

Never log API keys, endpoint tokens, authorization headers, or complete request

bodies containing secrets. For a suspected leak, stop and request rotation.