Skip to main content
Error responses are primarily described by the HTTP status, error.type, error.code, error.message, and X-Request-Id.

​
Error response shape

  • HTTP status: the final failure class for the request.
  • X-Request-Id: request tracing ID. If the client does not send one, the gateway generates it and tries to return it on failures.
  • error.message: human-readable error description for the caller.
  • error.type: error type. Stable ApiGo gateway errors currently use invalid_request_error. Upstream platform errors may use different values.
  • error.code: error code. ApiGo gateway errors use stable codes. Upstream platform errors may omit this field.
Example response
{
  "error": {
    "message": "upstream provider credentials unavailable",
    "type": "invalid_request_error",
    "code": "missing_upstream_key"
  }
}

​
Error sources

​
ApiGo gateway

error.codeHTTP statuserror.typeerror.messageMeaning
missing_upstream_key502invalid_request_errorupstream provider credentials unavailableThe upstream service is currently unavailable. Ask the platform administrator to check provider credentials.
invalid_upstream_key_info502invalid_request_errorinvalid key info responseThe upstream service configuration is invalid, so the request cannot be completed.
masked_upstream_key502invalid_request_errorupstream provider credentials are masked and cannot be usedThe upstream service credentials are unusable, so the request cannot be completed.

​
Upstream platform errors

Some requests may return errors directly from the upstream platform. In that case, rely on the actual HTTP status and the returned error object.
  • HTTP status: use the returned status as-is.
  • Response body: usually contains the platform’s error.type, error.code, and error.message.
  • X-Request-Id: keep it for support and log lookup.
  • Documentation boundary: do not treat all upstream type or code values as stable ApiGo gateway error codes.
Platform passthrough example
{
  "error": {
    "message": "daily credits exhausted",
    "type": "insufficient_quota"
  }
}
This 402 example means credits or balance are exhausted. It comes from the upstream platform and is not part of the stable ApiGo gateway error-code set.

​
Suggested debugging order

  1. Check the HTTP status first to tell whether the failure is a stable ApiGo gateway error or an upstream platform error.
  2. Keep the X-Request-Id for support and log lookup.
  3. If error.code is missing_upstream_key, invalid_upstream_key_info, or masked_upstream_key, contact the platform administrator to resolve the service configuration issue.
  4. If the response is an upstream platform error, use error.type, error.code, and error.message to diagnose quota, auth, or platform policy issues.