Error Handling & Rate Limiting - KPI Integration API

Response envelope

A single resource:

{ "data": { ... } }

A paginated list — see Pagination for details:

{
  "data": [ ... ],
  "meta": { "current_page": 1, "per_page": 10, "total": 42, "last_page": 5 }
}

An error:

{
  "error_code": "INVALID_API_KEY",
  "message": "Invalid API key."
}

A validation error (VALIDATION_FAILED) additionally includes an errors object with per-field messages:

{
  "error_code": "VALIDATION_FAILED",
  "message": "The given data was invalid.",
  "errors": { "per_page": ["The selected per page is invalid."] }
}

errors is only present for field-level validation failures (VALIDATION_FAILED); every other error returns just error_code and message.

Errors

The KPI Integration API uses standard HTTP status codes to indicate the success or failure of a request:

Status Code	Description
`200`	Success
`400`	Bad request
`401`	Missing, invalid, or expired API key
`403`	Key is valid but not allowed to access this resource, IP, or domain
`404`	Not found
`405`	HTTP method not allowed for this endpoint
`409`	Request is valid, but the requested resource isn’t ready yet (e.g. a report for an unpublished job) — see that endpoint’s documentation below for exactly which conditions apply
`422`	Unprocessable entity (validation failed)
`429`	Too many requests
`500`	Internal server error

error_code can be any of the following on any endpoint. Codes specific to one endpoint’s business logic (for example, report-readiness errors) are documented on that endpoint’s own page below.

Code	Status	Message
`MISSING_API_KEY`	401	API key is required.
`INVALID_API_KEY`	401	Invalid API key.
`API_KEY_EXPIRED`	401	API key has expired.
`FORBIDDEN`	403	You do not have access to this resource.
`IP_NOT_ALLOWED`	403	Request IP is not allowed.
`DOMAIN_NOT_ALLOWED`	403	Request domain/origin is not allowed.
`BAD_REQUEST`	400	Bad request.
`NOT_FOUND`	404	Resource not found.
`METHOD_NOT_ALLOWED`	405	The HTTP method is not allowed for this endpoint.
`VALIDATION_FAILED`	422	The given data was invalid.
`RATE_LIMIT_EXCEEDED`	429	Too many requests.
`INTERNAL_ERROR`	500	Something went wrong.

Rate limiting

The KPI Integration API is rate-limited to ensure fair usage. Every response includes headers describing your current limit:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47

If you exceed the limit, you’ll get a 429 response with a Retry-After header (seconds to wait before retrying):

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "error_code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests."
}

If the default limit is insufficient for your workflow, contact your account manager to request an adjustment.

​Response envelope

​Errors

​Rate limiting

Response envelope

Errors

Rate limiting