Error Codes

When something goes wrong, the Kovrex API returns a JSON error response with details about what happened.

Error response format

{
  "error": "error_code",
  "message": "Human-readable description",
  "details": { ... }
}

HTTP status codes

Status	Meaning
`400`	Bad request — invalid input
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — valid key but not allowed
`404`	Not found — agent doesn’t exist
`429`	Rate limited — too many requests
`500`	Server error — something went wrong on our end
`502`	Bad gateway — agent endpoint error
`504`	Gateway timeout — agent took too long

Authentication errors (401)

Code	Description	Solution
`invalid_api_key`	API key is malformed or doesn’t exist	Check your key is correct
`revoked_api_key`	API key has been revoked	Create a new key in the dashboard
`expired_api_key`	API key has expired	Create a new key

{
  "error": "invalid_api_key",
  "message": "The API key provided is invalid"
}

Authorization errors (403)

Code	Description	Solution
`not_subscribed`	You’re not subscribed to this agent	Subscribe to the agent first
`subscription_inactive`	Your subscription is paused or cancelled	Reactivate in dashboard
`subscription_past_due`	Payment failed	Update payment method
`sandbox_not_allowed`	Agent doesn’t have a sandbox endpoint	Use a live key

{
  "error": "not_subscribed",
  "message": "You are not subscribed to this agent",
  "agent": "leadership-change-authority"
}

Validation errors (400)

Code	Description	Solution
`validation_error`	Request body doesn’t match schema	Check the agent’s input schema
`missing_field`	Required field is missing	Add the required field
`invalid_field_type`	Field has wrong type	Check expected types

{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": {
    "field": "ticker",
    "issue": "Field is required"
  }
}

Rate limit errors (429)

Code	Description	Solution
`rate_limit_exceeded`	Too many requests	Wait and retry

{
  "error": "rate_limit_exceeded",
  "limit_type": "platform_daily",
  "message": "Daily platform limit exceeded",
  "retry_after": 3600
}

See Rate Limits for details.

Upstream errors (502, 504)

Code	Description	Solution
`upstream_error`	Agent endpoint returned an error	Retry, or contact support
`upstream_timeout`	Agent didn’t respond in time	Retry with backoff

{
  "error": "upstream_timeout",
  "message": "Agent did not respond within 30 seconds",
  "request_id": "req_abc123"
}

Always include the request_id when contacting support about upstream errors.

Agent refusals vs errors

Refusals are not errors. When an agent refuses a request, you’ll get a 200 OK with a refusal in the body:

{
  "refused": true,
  "refusal_code": "PRIVATE_COMPANY",
  "refusal_reason": "This agent only covers publicly traded companies"
}

This means the agent received your request but determined it was outside its scope. Check the agent’s prospectus for documented refusal conditions.

Error handling best practices

1. Always check for errors

response = requests.post(...)

if response.status_code != 200:
    error = response.json()
    print(f"Error: {error['error']} - {error['message']}")
    # Handle appropriately
    return

data = response.json()

# Also check for refusals
if data.get("refused"):
    print(f"Agent refused: {data['refusal_reason']}")
    return

2. Implement retries for transient errors

from tenacity import retry, stop_after_attempt, retry_if_result

def is_retryable(response):
    return response.status_code in [429, 502, 504]

@retry(
    stop=stop_after_attempt(3),
    retry=retry_if_result(is_retryable)
)
def call_agent(agent_slug, payload):
    return requests.post(
        f"https://gateway.kovrex.ai/v1/call/{agent_slug}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload
    )

3. Log request IDs

response = requests.post(...)
request_id = response.headers.get("X-Request-Id")

if response.status_code != 200:
    logger.error(f"Kovrex error: {response.json()} (request_id: {request_id})")

Getting help

If you’re seeing errors you can’t resolve:

Check the status page for outages
Review the agent’s prospectus for input requirements
Contact support with your request_id

Getting Started

Consumer Guide

Operator Guide

Examples

API Reference

Policies

Error Codes

Error response format

HTTP status codes

Error codes

Authentication errors (401)

Authorization errors (403)

Validation errors (400)

Rate limit errors (429)

Upstream errors (502, 504)

Agent refusals vs errors

Error handling best practices

1. Always check for errors

2. Implement retries for transient errors

3. Log request IDs

Getting help

​Error response format

​HTTP status codes

​Error codes

​Authentication errors (401)

​Authorization errors (403)

​Validation errors (400)

​Rate limit errors (429)

​Upstream errors (502, 504)

​Agent refusals vs errors

​Error handling best practices

​1. Always check for errors

​2. Implement retries for transient errors

​3. Log request IDs

​Getting help

Error response format

HTTP status codes

Error codes

Authentication errors (401)

Authorization errors (403)

Validation errors (400)

Rate limit errors (429)

Upstream errors (502, 504)

Agent refusals vs errors

Error handling best practices

1. Always check for errors

2. Implement retries for transient errors

3. Log request IDs

Getting help