Error Codes

Every error response from the Chronary API follows a consistent shape, making it straightforward to handle errors programmatically.

Error response format

All errors return a JSON body with a single error object:

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request body",
    "param": "start_time",
    "request_id": "req_abc123"
  }
}

Field	Type	Description
type	string	Machine-readable error type (see table below)
message	string	Human-readable explanation of what went wrong
param	string | null	The specific parameter that caused the error, when applicable
request_id	string	Unique identifier for the request, useful for debugging

Error types

validation_error — 400 Bad Request

The request body, query parameters, or path parameters failed validation.

Common causes:

• Missing required fields
• Invalid date format in start_time or end_time
• Value out of allowed range (e.g., negative duration)
• Unknown fields in the request body

How to fix: Check the param field in the error response to identify which field is invalid. Refer to the API reference for the expected format.

---

authentication_error — 401 Unauthorized

The API key is missing, malformed, or revoked.

Common causes:

• Missing Authorization header entirely
• Using Authorization: chr_sk_... instead of Authorization: Bearer chr_sk_...
• Using a revoked or rotated API key
• Using a test key (chr_sk_test_) against production data or vice versa

How to fix: Verify the Authorization: Bearer <your_api_key> header is present and uses a valid, active key from the console.

---

forbidden — 403 Forbidden

The authenticated key does not have permission to perform the requested action.

Common causes:

• Attempting to modify an event with source: "ical_subscription" (external events are read-only)
• Accessing a resource that belongs to a different organization
• Performing an action not allowed on your current plan

How to fix: Check that the resource belongs to your organization and that the source field allows modification. External events synced via iCal subscriptions cannot be edited through the API.

---

not_found — 404 Not Found

The requested resource does not exist or is not accessible from your organization.

Common causes:

• Typo in the resource ID (e.g., agt_ vs cal_ prefix mismatch)
• The resource was deleted
• The resource belongs to a different organization

How to fix: Verify the ID is correct and uses the right prefix (agt_ for agents, cal_ for calendars, evt_ for events). Confirm the resource belongs to the same organization as your API key.

Tip

Chronary returns 404 (not 403) for resources in other organizations. This prevents leaking information about whether a resource exists.

---

conflict — 409 Conflict

The request conflicts with the current state of a resource.

Common causes:

• Creating an agent with an email address already in use
• Creating a duplicate webhook subscription for the same URL and event type

How to fix: Use a different value for the conflicting field, or fetch the existing resource instead of creating a new one.

---

rate_limit_error — 429 Too Many Requests

You have exceeded the per-key rate limit of 10 requests per second.

Common causes:

• Sending bursts of requests without throttling
• Running parallel operations without a concurrency limit

How to fix: Respect the Retry-After header in the response. Implement exponential backoff with jitter. See the Rate Limits page for a retry code example.

---

quota_exceeded — 429 Too Many Requests

Your organization has exhausted its monthly quota for a specific resource.

Common causes:

• Hitting the monthly event creation limit on the Free plan (5,000/mo)
• Exceeding the monthly API call limit (50,000/mo on Free)

How to fix: Check your current usage with GET /v1/usage. Upgrade your plan in the console or wait for the automatic monthly reset. See Rate Limits for quota details by plan.

Note

Both rate_limit_error and quota_exceeded return HTTP 429. Distinguish them by the type field in the error response.

---

internal_error — 500 Internal Server Error

Something went wrong on the Chronary server.

Common causes:

• Transient infrastructure issue
• Unexpected edge case in request processing

How to fix: Retry the request with exponential backoff. If the error persists after multiple retries, contact support with the request_id from the error response.

Using request_id for debugging

Every API response — successful or not — includes a request_id in the response body and as the X-Request-Id response header. This ID uniquely identifies your request in Chronary’s logging infrastructure.

When contacting support about an error:

1. Include the request_id from the error response
2. Note the approximate time the error occurred
3. Include the endpoint and method you called

This allows the support team to trace the exact request through the system and diagnose the issue quickly.

# The request_id appears in both the response body and headers
curl -v https://api.chronary.ai/v1/agents/agt_nonexistent \
  -H "Authorization: Bearer chr_sk_test_your_key_here"

# Response header: X-Request-Id: req_abc123
# Response body:
# {
#   "error": {
#     "type": "not_found",
#     "message": "Agent not found",
#     "param": null,
#     "request_id": "req_abc123"
#   }
# }