Common errors - Kairo Connect Docs

Kairo Shield errors follow RFC 7807 (Problem Details for HTTP APIs):

{
  "type": "about:blank",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request validation failed",
  "errors": [
    {
      "field": "body.amount",
      "message": "Input should be greater than 0",
      "type": "greater_than"
    }
  ]
}

The errors field appears only on validation errors (422).

HTTP status codes

Code	Typical title	When it occurs
401	Unauthorized	Missing or invalid API Key
403	Forbidden	Suspended client, onboarding, or fraud consent not granted
409	Duplicate Transaction	Same `transaction_id` within idempotency window (24 h)
422	Validation Error	Invalid data (UUID, amount ≤ 0, unknown enum, etc.)
429	Too Many Requests	Rate limit exceeded
503	Service Unavailable	Maintenance mode active
504	Scoring Timeout	Scoring exceeded SLA (`scoring_timeout_ms`)
500	Internal Server Error	Unexpected error; contact support with `request_id` if available

Scoring errors

Situation	Code	Recommended action
Duplicate `transaction_id`	409	Use a new UUID or rely on cached score from first submission
Inference timeout	504	Retry with backoff; report if persistent
Consent not granted	403	Request activation from Kairo Connect

Support

When reporting issues, include the scoring response request_id when available. tecnologia@kairoconnect.com