Error Handling

Overview

All Opelyx API errors use the RFC 9457 Problem Details format with content type application/problem+json. This provides structured, machine-readable error information.

Error Response Format

{
  "type": "https://api.opelyx.com/problems/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid ZIP code format. Expected 5 digits.",
  "instance": "/v1/health/plans"
}

Field	Description
type	URI identifying the error type
title	Human-readable error category
status	HTTP status code
detail	Specific error message for this occurrence
instance	The request path that generated the error

Error Types

Status	Type	Meaning
400	validation-error	Invalid request parameters
401	unauthorized	Missing or invalid API key
402	payment-required	Feature requires a higher subscription tier
404	not-found	Resource does not exist
405	method-not-allowed	HTTP method not supported on this endpoint
406	not-acceptable	Non-JSON Accept header
429	rate-limit-exceeded	Daily rate limit exceeded
500	internal-error	Unexpected server error

Extension Fields

Some error responses include additional fields:

Validation Errors (400)

{
  "type": "https://api.opelyx.com/problems/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid input.",
  "errors": [
    { "field": "age", "message": "Expected number, received string" },
    { "field": "zip", "message": "String must contain exactly 5 characters" }
  ]
}

Payment Required (402)

{
  "type": "https://api.opelyx.com/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "Plan comparison requires a Pro subscription.",
  "required_tier": "pro",
  "upgrade": "https://opelyx.com/#pricing"
}

Rate Limited (429)

Check the Retry-After header to know when to retry:

{
  "type": "https://api.opelyx.com/problems/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Daily request limit reached. Resets at midnight UTC.",
  "upgrade": "https://opelyx.com/#pricing"
}

Tip

Always check the Retry-After response header (in seconds) rather than implementing a fixed delay. Combine this with the RateLimit-Reset header (Unix timestamp) for precise rate limit tracking.

Best Practices

1. Always check status before processing response data
2. Parse type to programmatically identify error categories
3. Log instance and X-Request-Id for debugging and support requests
4. Handle 429 gracefully with exponential backoff respecting Retry-After
5. Show detail to users as it contains actionable error messages