Error reference

All errors follow the same envelope. Use error.code for programmatic handling. Never match on error.message.

Error envelope

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable developer message.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": { "candidates": ["gal", "imp-gal"] }
  }
}

json

{
  "error": {
    "code": "INCOMPATIBLE_UNITS",
    "message": "The units belong to incompatible categories.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error codes

Code	HTTP	Meaning
`INVALID_REQUEST`	400	Request schema is invalid (missing fields, wrong types, unknown properties)
`INVALID_VALUE`	400	Measurement value is not a valid decimal string
`OUT_OF_RANGE`	400	Value is outside the physical range for the unit (for example negative mass, or temperature below absolute zero)
`UNKNOWN_UNIT`	400 / 404	Unit identifier cannot be resolved (400 for conversions, 404 for resource lookup)
`AMBIGUOUS_UNIT`	400	Unit alias matches multiple canonical units; details.candidates lists allowed IDs
`INCOMPATIBLE_UNITS`	422	Source and target units belong to different categories (for example mass to length). Also returned when Normalize, Unit price, or Substance convert cannot combine the given units (mixed temperatures, mixed categories, or units that are not mass or volume)
`UNKNOWN_CATEGORY`	404 (400 on GET /v1/substances)	Category identifier does not exist (category path or units?category= filter, or the substances category filter)
`NOT_FOUND`	404	The requested endpoint path does not exist
`METHOD_NOT_ALLOWED`	405	HTTP method is not supported for this path; check the Allow header
`BATCH_LIMIT_EXCEEDED`	400	Batch contains more than the plan or service maximum (up to 100) conversions
`PAYLOAD_TOO_LARGE`	413	Request body exceeds the maximum allowed size
`UNSUPPORTED_MEDIA_TYPE`	415	POST request has an unsupported Content-Type (must be application/json)
`UNAUTHORIZED`	401	Authorization header is missing. A header that is not in the form Bearer <token> returns INVALID_API_KEY
`INVALID_API_KEY`	401	API key is invalid, inactive, or revoked
`UNKNOWN_SUBSTANCE`	400	The substance id is not in GET /v1/substances
`UNKNOWN_CURRENCY`	400	The currency code is not one of the supported ECB currencies
`PLAN_REQUIRED`	403	Your plan does not include this feature; upgrade to use it
`RATE_NOT_FOUND`	404	No exchange rates are available for the requested date
`QUOTA_EXCEEDED`	429	Monthly conversion quota used; upgrade your plan or wait for the quota to reset (no Retry-After)
`RATE_LIMIT_EXCEEDED`	429	Burst rate limit exceeded; response includes Retry-After: 60
`INTERNAL_ERROR`	500	Unexpected server error; provide the X-Request-Id to support
`SERVICE_UNAVAILABLE`	503	A required service dependency is unavailable; retry with exponential backoff

Request ID. Every response includes an X-Request-Id header. Include this ID when contacting support. Never send your API key.