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."
  }
}

Field	Type	Description
`type`	`string`	Machine-readable error type
`message`	`string`	Human-readable error description

Error code reference

400 — Bad Request

invalid_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.

invalid_date_range

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.

too_many_campaigns

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

authentication_error

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

key_revoked

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

permission_error

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.

plan_insufficient

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.

white_label_not_available

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

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

diagnostic_in_progress

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

campaign_not_synced

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

rate_limit_error

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

api_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:

Retry the request after a short delay
If the error persists, contact support@klayrai.com with the requestId from the error response
Check status.klayrai.com for any ongoing incidents

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.

Handle every status code — At minimum, handle 400, 401, 403, 404, 429, and 500
Implement retries for transient errors — 429 and 500 errors are usually transient and should be retried with backoff
Do not retry 400, 401, 403, or 404 — These indicate a problem with the request itself, not a transient server issue
Use structured error handling — Parse the type field for programmatic error handling rather than matching on message strings

Getting Started

Resources

Error Codes

Error Codes

Error response format

Error code reference

400 — Bad Request

401 — Unauthorized

403 — Forbidden

404 — Not Found

409 — Conflict

422 — Unprocessable Entity

429 — Too Many Requests

500 — Internal Server Error

Error handling best practices

​Error Codes

​Error response format

​Error code reference

​400 — Bad Request

​401 — Unauthorized

​403 — Forbidden

​404 — Not Found

​409 — Conflict

​422 — Unprocessable Entity

​429 — Too Many Requests

​500 — Internal Server Error

​Error handling best practices

Error Codes

Error response format

Error code reference

400 — Bad Request

401 — Unauthorized

403 — Forbidden

404 — Not Found

409 — Conflict

422 — Unprocessable Entity

429 — Too Many Requests

500 — Internal Server Error

Error handling best practices