Error Handling

All PickLayer API errors follow a consistent envelope format with HTTP status codes and typed error messages.

Error Response Format


{
  "code": 400,
  "message": "Messages array is required and must not be empty",
  "type": "VALIDATION",
  "data": { "field": "messages" }
}

Field	Description
`code`	HTTP status code
`message`	Human-readable error description
`type`	Error category (see table below)
`data`	Additional context (field names, limits, etc.)

Error Types

HTTP	Type	Meaning
400	`VALIDATION`	JSON schema violation or missing required fields
401	`AUTHENTICATION`	Access token invalid or expired
402	`PAYMENT_REQUIRED`	Insufficient funds, cap exceeded, or billing issue
403	`FORBIDDEN`	Suspended user or forbidden route
404	`NOT_FOUND`	Organization, application, or resource not found
409	`CONFLICT`	Duplicate handler, idempotency mismatch
429	`QUOTA`	Rate limit or spend ceiling exceeded
5xx	`SERVER_ERROR`	Provider failure or internal error

Billing Error Codes

When billing validation fails, the data field includes a specific reason code:

Reason	HTTP	Description
`NOT_FUNDED`	402	User plan assignment is not funded
`FUNDING_MODE_INACTIVE`	400	Funding mode is not active
`PERIOD_INACTIVE`	400	Billing period outside start/end dates
`PERIOD_INVALID`	400	Billing period start or end date is missing
`CAP_NOT_SET`	400	Plan has no monthly cost cap configured
`CAP_EXCEEDED`	402	User has exceeded their monthly cost cap
`POOL_EXHAUSTED`	402	Organization/app pool has insufficient credits
`INSUFFICIENT_FUNDS`	402	Insufficient funds in wallet
`PRICING_RATE_NOT_FOUND`	404	No pricing rate found for model
`ASSIGNMENT_NOT_FOUND`	404	User plan assignment not found

Rate Limiting (429)

When rate limits are exceeded, the response includes retry information:


{
  "code": 429,
  "message": "Rate limit exceeded",
  "type": "QUOTA",
  "data": {
    "limitType": "requests_per_minute",
    "limitValue": 60,
    "currentValue": 61,
    "retryAfterSeconds": 45
  }
}

The Retry-After HTTP header is also set with the number of seconds to wait.

Provider Errors

When an upstream AI provider returns an error, PickLayer wraps it:


{
  "code": 502,
  "message": "Provider returned error: rate limit exceeded",
  "type": "SERVER_ERROR",
  "data": {
    "provider": "openai",
    "providerError": "Rate limit exceeded. Please retry after 20 seconds."
  }
}

Best Practices

Always check type for programmatic error handling
Use data.field in validation errors to highlight specific input issues
Respect Retry-After headers for rate limit errors
Log request_id from response headers for debugging with support