Error Codes

All errors return a JSON body with a consistent envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "start_date and end_date are required.",
    "request_id": "a3f2c1d0-1234-5678-abcd-ef0123456789"
  }
}

error.code is a closed enum in the OpenAPI `ErrorBody` (VALIDATION_ERROR, INVALID_API_KEY, RESOURCE_NOT_FOUND, ROUTE_NOT_FOUND, METHOD_NOT_ALLOWED, RATE_LIMIT_EXCEEDED, AUTH_FAILURE_THROTTLE, SERVICE_UNAVAILABLE, INTERNAL_ERROR). Code generators should map these literals; treat any other value as a forward-compatible extension.

For rate-limit errors, retry_after_seconds is also present:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded.",
    "request_id": "...",
    "retry_after_seconds": 42
  }
}

For validation errors, details may be present with field-level context. Canonical shape: each field key maps to a string array (even when there is only one message):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "limit cannot exceed 20.",
    "request_id": "...",
    "details": {
      "limit": ["limit cannot exceed 20."]
    }
  }
}

Some cap-exceeded errors add integer metadata keys alongside field errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "User has 1001 timesheets in range; maximum is 1000. Narrow start_date/end_date.",
    "request_id": "...",
    "details": {
      "timesheets_in_range": 1001,
      "timesheets_cap": 1000
    }
  }
}

Documented metadata keys: timesheets_in_range, timesheets_cap, log_count, log_cap. Most validation errors omit details entirely — read message first.

See validation-details section below.

request_id is always present and is unique per invocation. Include it when reporting issues.

Error Code Reference#

INVALID_API_KEY — 401 Unauthorized#

The X-APPLOYE-API-KEY header is missing, malformed, or references a revoked API key.

Common causes:

• Header was not sent.
• The API key was rotated or revoked. Keys are cached in-process for up to 120 seconds; wait up to 2 minutes after revocation before testing again.
• The key belongs to a different organization than the one you are querying.

Response headers: None specific to auth errors.

RATE_LIMIT_EXCEEDED — 429 Too Many Requests#

Your organization has exceeded the allowed request rate for this endpoint.

Response headers:

The global fallback is 30 requests per 60 seconds per organization, HTTP method, and canonical resource group. List and detail routes share a bucket. Overrides may apply.

How to handle: Read the Retry-After header and wait before retrying. Do not retry immediately — the counter does not reset until the window expires.

AUTH_FAILURE_THROTTLE — 429 Too Many Requests#

Your IP address has exceeded the authentication-failure threshold (10 failures in 60 seconds). All further requests from this IP are blocked until the failure window resets, even if you supply a valid API key.

Response headers:

This error differs from RATE_LIMIT_EXCEEDED in that it is IP-based, not org-based, and fires before API key validation.

SERVICE_UNAVAILABLE — 503 Service Unavailable#

The API authenticated the key but could not complete Redis quota accounting, so it failed closed. The response includes Retry-After: 5; wait, add jitter, and retry.

RESOURCE_NOT_FOUND — 404 Not Found#

The requested resource does not exist within your organization. The route was recognised and the handler ran; this is not a mistyped URL.

Common causes and affected endpoints:

Note: Inactive clients and inactive projects do not return 404 from their primary endpoints (only client ID is checked for existence, not is_active status). See Filters guide.

Note: GET /v1/clockinouts/ with an unknown team_id returns 200 with empty results, not 404. This is intentional — see Filters guide.

ROUTE_NOT_FOUND — 404 Not Found#

The URL path is not a valid Partner API endpoint for this Lambda (or API Gateway routed to the wrong function). No business logic ran.

{
  "error": {
    "code": "ROUTE_NOT_FOUND",
    "message": "Route not found.",
    "request_id": "..."
  }
}

Common causes: typo in path, trailing slash omitted or added incorrectly, calling an endpoint that lives on a different Lambda integration.

Do not confuse with `RESOURCE_NOT_FOUND`: if you GET /v1/clients/{client_id}/ with a valid path shape but a UUID that does not exist, you receive RESOURCE_NOT_FOUND with a resource-specific message.

METHOD_NOT_ALLOWED — 405 Method Not Allowed#

The Partner API is read-only. Only GET (and OPTIONS for CORS preflight) are supported.

{
  "error": {
    "code": "METHOD_NOT_ALLOWED",
    "message": "Method not allowed.",
    "request_id": "..."
  }
}

Common causes: POST, PUT, PATCH, or DELETE to any /v1/... path.

VALIDATION_ERROR — 400 Bad Request#

A request parameter failed validation.

Common messages:

#### VALIDATION_ERROR details shape

Handlers normalize scalar strings to one-element arrays at the error boundary. Clients should accept field values as arrays of strings.

INTERNAL_ERROR — 500 Internal Server Error#

An unexpected error occurred within the Lambda function.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred.",
    "request_id": "..."
  }
}

request_id is the most useful field here — include it in any support request. Database errors, unhandled exceptions, and infrastructure outages are all surfaced as INTERNAL_ERROR.

Status Code Summary#