API Conventions

Behaviors that apply to every endpoint in the Lumen Partners API.

Error format

All errors return an HTTP status code matching the error class and a JSON body shaped like:

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Human-readable description of what went wrong."
  }
}

code is a stable, machine-readable identifier you can branch on. message is human-facing and may change without notice.

Endpoint-specific error codes are listed on each endpoint's reference page.

Common error codes

These codes can be returned by any endpoint:

HTTP	code	When
400	INVALID_INPUT	The request was malformed (bad JSON, missing required fields, wrong field types).
401	UNAUTHORIZED	The X-Partner-Api-Key header is missing, malformed, or invalid.
429	RATE_LIMIT	You have exceeded your request budget. The Retry-After header indicates how long to wait.
5xx	INTERNAL_ERROR	A Lumen-side problem. Safe to retry with exponential backoff.

Versioning

The API uses path-based versioning (/partners/v1/, /partners/v2/, ...). Within a major version:

• Additive changes are non-breaking. New endpoints, new optional request fields, new response fields, and new enum values may be introduced at any time. Your integration should ignore unknown response fields rather than fail on them.
• Removed or changed fields are breaking. Breaking changes ship in a new major version with a published deprecation timeline of at least 6 months.

When new alert subtypes or other enum values appear, treat them as their nearest known equivalent (or pass them through) rather than rejecting them.