Source: docs/integration/errors.md

API Errors (MVP)

Format

{
  "error": "Human readable message",
  "code": "MACHINE_CODE"
}

The HTTP channel (POST /v1/channels/http/messages) returns its error as an

object:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "..."
  }
}

For each endpoint, the OpenAPI contract is authoritative

for the exact status codes and response schema.

Main codes

400 BAD_REQUEST

• Typical cause: invalid payload in webhook.

401 UNAUTHORIZED

• Typical cause: missing Authorization: Bearer <api_key> or invalid key.

403 FORBIDDEN

• Typical cause: the API key does not have access to the requested resource.

404 NOT_FOUND

• Typical cause: the requested resource does not exist or is unavailable to the API key.

405 METHOD_NOT_ALLOWED

• Typical cause: wrong HTTP method on endpoint.

409 CONFLICT

• Typical cause: attempting to approve/reject an action not in pending state.

413 PAYLOAD_TOO_LARGE

• Typical cause: a capability-credential request exceeds the allowed secret size.

422 VALIDATION_ERROR

• Typical cause: invalid JSON or a request body that does not meet the endpoint schema.

500 INTERNAL_ERROR

• Typical cause: unexpected internal failure (e.g., failed enqueue on approval).

503 SERVICE_UNAVAILABLE

• Typical cause: the capability credential vault is temporarily unavailable. Retry

only according to the host application's retry policy.