Errors

Error types, codes, and HTTP status codes returned by the Checkrd API.

Errors

The Checkrd API returns errors in a consistent JSON format:

json

{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameter",
    "message": "Name is required.",
    "param": "name"
  }
}

Error Types

Type	Description
`validation_error`	The request body or parameters are invalid.
`authentication_error`	Missing or invalid authentication credentials.
`authorization_error`	Valid credentials, but insufficient permissions.
`not_found_error`	The requested resource does not exist.
`conflict_error`	The request conflicts with existing state (e.g., duplicate idempotency key).
`rate_limit_error`	Too many requests. Retry after the `Retry-After` header value.
`api_error`	An internal server error. Contact support if persistent.

HTTP Status Codes

Code	Meaning
`200`	Success.
`201`	Resource created.
`400`	Validation error. Check the `message` and `param` fields.
`401`	Authentication required or token expired.
`403`	Insufficient role or plan tier.
`404`	Resource not found.
`409`	Conflict (concurrent idempotency key or duplicate resource).
`429`	Rate limited. Respect `Retry-After` header.
`500`	Internal error. The request body is never leaked in error messages.

Handling Errors

All error responses include a type and message. Use type for programmatic handling and message for display:

python

import httpx

response = httpx.post("https://api.checkrd.io/v1/agents", ...)
if response.status_code >= 400:
    error = response.json()["error"]
    if error["type"] == "rate_limit_error":
        retry_after = int(response.headers["Retry-After"])
        # wait and retry
    elif error["type"] == "validation_error":
        print(f"Invalid field: {error.get('param')}: {error['message']}")

Authentication Agents