Errors

Every non-2xx response uses one envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "A human-readable description.",
    "param": "product_id",
    "doc_url": "https://docs.interglobe.io/errors/validation_failed"
  },
  "request_id": "req_1a2b3c"
}

Match on code, never message

The code is stable and enumerated — it never changes meaning and is safe to branch on. The message is for humans and may change. type maps to the HTTP status class; param (when present) names the offending field; doc_url links to the explanation for that exact code.

The full list lives in the error-code registry. Common ones:

Code	HTTP	When
validation_failed	400	Bad request body/params
unauthenticated	401	Missing/invalid key
forbidden	403	Key lacks the scope
not_found	404	Resource doesn’t exist here
insufficient_balance	402	Wallet too low
rate_limited	429	Slow down (see Retry-After)

Always log the request_id

Every response carries a request_id (also the Request-Id header). Include it when you contact support — it lets us find the exact request instantly.