Error Codes

All API errors follow a consistent envelope format:


{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": [...]
  }
}

The details array is present only for validation errors and contains per-field diagnostics.

Error codes

Code	HTTP Status	Description
`AUTHENTICATION_FAILED`	401	Invalid, missing, or revoked API key
`FORBIDDEN`	403	Valid credentials but insufficient permissions
`VALIDATION_ERROR`	400	Request body or query params failed validation
`NOT_FOUND`	404	Resource does not exist (or belongs to another tenant)
`CONFLICT`	409	Resource already exists (e.g. duplicate `agentId`)
`NORMALIZATION_FAILED`	422	Event has unknown category or missing required payload fields
`INTERNAL_ERROR`	500	Unexpected server error

Validation error details

When the code is VALIDATION_ERROR, the details array contains one entry per field:


{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "path": ["eventId"],
        "message": "Invalid uuid",
        "code": "invalid_string"
      },
      {
        "path": ["category"],
        "message": "Required",
        "code": "invalid_type"
      }
    ]
  }
}

Each detail contains:

Field	Type	Description
`path`	string[]	JSON path to the invalid field
`message`	string	Human-readable error
`code`	string	Zod validation error code

HTTP status codes

Status	Meaning	Retryable?
`200`	Success	—
`201`	Created	—
`202`	Accepted (event ingested)	—
`400`	Bad request	No — fix the request
`401`	Unauthorized	No — check API key
`403`	Forbidden	No — check permissions
`404`	Not found	No
`409`	Conflict	No — resource exists
`422`	Unprocessable entity	No — fix the payload
`429`	Rate limited	Yes — respect `Retry-After`
`500`	Internal error	Yes — with backoff
`502`	Bad gateway	Yes — with backoff
`503`	Service unavailable	Yes — with backoff
`504`	Gateway timeout	Yes — with backoff

SDK error classes

TypeScript


import {
  KaplaixError,        // API returned an error status
  KaplaixNetworkError, // Network-level failure
  KaplaixTimeoutError, // Request timed out
} from "@kaplaix/sdk-ts";

Python


from kaplaix import (
    KaplaixError,        # API returned an error status
    KaplaixNetworkError, # Network-level failure
    KaplaixTimeoutError, # Request timed out
)

Tenant isolation

Cross-tenant access always returns 404, never 403. The API never confirms or denies the existence of resources belonging to other tenants.