Skip to main content

​
Error Codes

All KlayrAI API errors follow a consistent JSON format. This page documents every error code, what causes it, and how to resolve it.

​
Error response format

Every error response includes: 
{
  "error": {
    "type": "error_type_here",
    "message": "A human-readable description of what went wrong."
  }
}
FieldTypeDescription
typestringMachine-readable error type
messagestringHuman-readable error description

​
Error code reference

​
400 — Bad Request

Cause: The request body or query parameters are malformed or missing required fields.Example:
{
  "error": {
    "type": "invalid_request",
    "message": "The 'account_id' field is required."
  }
}
Resolution: Check the API reference for required parameters and ensure your request body is valid JSON with the correct field types.
Cause: The date range provided is invalid — either the start date is after the end date, or the range exceeds the maximum allowed period (90 days).Example:
{
  "error": {
    "type": "invalid_date_range",
    "message": "Start date must be before end date. Maximum range is 90 days."
  }
}
Resolution: Ensure from is before to and the range does not exceed 90 days.
Cause: More than 20 campaign IDs were provided in a single request (applies to report generation).Example:
{
  "error": {
    "type": "too_many_campaigns",
    "message": "Maximum of 20 campaign IDs allowed per report. You provided 25."
  }
}
Resolution: Split your request into multiple reports with 20 or fewer campaigns each.

​
401 — Unauthorized

Cause: The API key is missing, malformed, or invalid.Example:
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key. Check that your API key is correct and has not been revoked."
  }
}
Resolution:
  • Verify the x-api-key header is present in your request
  • Check that the key starts with klyr_live_ or klyr_test_
  • Ensure the key has not been revoked in your dashboard settings
  • Confirm there are no extra spaces or characters in the key
Cause: The API key was previously valid but has been revoked.Example:
{
  "error": {
    "type": "key_revoked",
    "message": "This API key has been revoked. Create a new key in your dashboard settings."
  }
}
Resolution: Create a new API key in Settings > API Keys and update your application.

​
403 — Forbidden

Cause: The API key does not have permission to access the requested resource. This typically occurs when trying to access a campaign or account that belongs to a different workspace.Example:
{
  "error": {
    "type": "permission_error",
    "message": "You do not have access to this resource."
  }
}
Resolution: Verify that the resource ID belongs to your workspace. API keys can only access data within their own workspace.
Cause: Your current plan does not include API access. The API is available on the Agency plan only.Example:
{
  "error": {
    "type": "plan_insufficient",
    "message": "API access requires the Agency plan. Upgrade at https://app.klayrai.com/settings/billing."
  }
}
Resolution: Upgrade to the Agency plan at app.klayrai.com/settings/billing.
Cause: White-label report options were requested, but this feature requires the Agency plan.Example:
{
  "error": {
    "type": "white_label_not_available",
    "message": "White-label reports are available on the Agency plan."
  }
}
Resolution: Upgrade to the Agency plan or remove the whiteLabel object from your request.

​
404 — Not Found

Cause: The requested resource does not exist or is not accessible in your workspace.Example:
{
  "error": {
    "type": "not_found",
    "message": "Campaign 'camp_xyz999' not found."
  }
}
Resolution:
  • Check the resource ID for typos
  • Verify the resource exists by listing resources first (e.g., GET /v1/campaigns)
  • Ensure the resource belongs to your workspace

​
409 — Conflict

Cause: A diagnostic is already running for the specified campaign. Only one diagnostic can run per campaign at a time.Example:
{
  "error": {
    "type": "diagnostic_in_progress",
    "message": "A diagnostic is already running for campaign camp_abc123. Please wait for it to complete."
  }
}
Resolution: Wait for the current diagnostic to complete (typically 5-10 seconds) and then try again, or retrieve the existing diagnostic result.

​
422 — Unprocessable Entity

Cause: The campaign’s data has not been synced from Meta yet. Diagnostics require synced data.Example:
{
  "error": {
    "type": "campaign_not_synced",
    "message": "Campaign camp_abc123 has not been synced yet. Data sync is in progress."
  }
}
Resolution: Wait for the initial sync to complete. For newly connected accounts, this typically takes 30-60 seconds.

​
429 — Too Many Requests

Cause: You have exceeded the rate limit for your API key.Example:
{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Please retry after 12 seconds."
  }
}
Resolution: Implement exponential backoff with jitter. Check the meta.remaining_requests field in successful responses to monitor your usage. See the Rate Limits page for detailed guidance.

​
500 — Internal Server Error

Cause: An unexpected error occurred on the KlayrAI server.Example:
{
  "error": {
    "type": "api_error",
    "message": "An internal error occurred. Please try again. If the problem persists, contact support@klayrai.com."
  }
}
Resolution:

​
Error handling best practices

Always check the HTTP status code first, then the type field in the error body. Do not rely on parsing the message field — it may change between API versions.
  1. Handle every status code — At minimum, handle 400, 401, 403, 404, 429, and 500
  2. Implement retries for transient errors — 429 and 500 errors are usually transient and should be retried with backoff
  3. Do not retry 400, 401, 403, or 404 — These indicate a problem with the request itself, not a transient server issue
  4. Use structured error handling — Parse the type field for programmatic error handling rather than matching on message strings