Errors

HTTP status codes and error response format.

The API uses standard HTTP status codes and returns errors as JSON with an error field.

Error format

All errors follow this shape:

{
  "error": "Human-readable error message"
}

Some validation errors on usage submission include per-event details:

{
  "accepted": 0,
  "rejected": 1,
  "events": [
    {
      "event_id": "evt-001",
      "status": "rejected",
      "error": "Metric 'unknown_metric' not in pricing program"
    }
  ]
}

Status codes

Code	Meaning	When
`200`	Success	Request completed successfully
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Missing, invalid, or expired API key
`404`	Not Found	Resource doesn't exist or doesn't belong to your account
`500`	Internal Server Error	Something went wrong on our end

Common errors

Authentication errors (401)

Error	Cause
`Missing API key`	No `Authorization` or `X-Api-Key` header
`Invalid API key`	Key doesn't match any active key
`API key expired`	Key has passed its expiration date

Usage submission errors

These appear in the events array with status: "rejected":

Error	Cause
`Contract not found or has no customer`	The `external_contract_id` doesn't match any active contract
`No approved pricing program`	The contract doesn't have an approved pricing program yet
`Metric 'X' not in pricing program`	The metric name doesn't match any usage rule

Not found errors (404)

Returned when looking up a specific resource:

{
  "error": "Not found"
}

This means either the resource doesn't exist or it belongs to a different company.

Retry guidance

401 — Don't retry. Fix your API key.
404 — Don't retry. Check the resource ID.
400 — Don't retry. Fix the request.
500 — Safe to retry with exponential backoff. Usage submissions are idempotent via event_id.