Errors and Limits

Error response format

Phase returns structured error responses.

{
  "code": "VALIDATION_ERROR",
  "detail": "Date range cannot exceed 365 days"
}

Status codes

• 400 Bad Request

  • Invalid query parameters
  • Unsupported query shapes
  • Date range larger than 365 days

• 401 Unauthorized

  • Missing Authorization header
  • Malformed bearer key
  • Invalid, expired, revoked, or unauthorized key

• 403 Forbidden

  • The key is valid, but it cannot access the requested app or resource

• 422 Unprocessable Entity

  • Route-level enum or query validation failed before the request reached the handler

• 429 Too Many Requests

  • The rate limit was exceeded

• 500 Internal Server Error

  • An unexpected server error occurred

Rate limit headers

When rate limiting applies, responses may include these headers:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset
• Retry-After

Request limits

Current limits:

• Maximum report range: 365 days
• Maximum breakdown size: 50 rows
• Default breakdown size: 10 rows
• Maximum raw page size: 50

Consistency

Phase analytics responses are eventually consistent.

• Recently ingested data may take a short time to appear in reports.
• Every report response includes a meta object.
• meta.generatedAt tells you when the response was created.
• meta.identityModel is currently user.