Error reference

All errors follow the same envelope. Useerror.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)
`UNKNOWN_CATEGORY`	404	Category identifier does not exist (category path or units?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
`INVALID_API_KEY`	401	API key is invalid, inactive, or revoked
`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 anX-Request-Id header. Include this ID when contacting support. Never send your API key.