Error Codes

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 MaaS gateway errors currently use invalid_request_error. Upstream platform errors may use different values.
error.code: error code. MaaS 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

MaaS gateway

`error.code`	HTTP status	`error.type`	`error.message`	Meaning
`missing_upstream_key`	`502`	`invalid_request_error`	`upstream provider credentials unavailable`	The upstream service is currently unavailable. Ask the platform administrator to check provider credentials.
`invalid_upstream_key_info`	`502`	`invalid_request_error`	`invalid key info response`	The upstream service configuration is invalid, so the request cannot be completed.
`masked_upstream_key`	`502`	`invalid_request_error`	`upstream provider credentials are masked and cannot be used`	The 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 MaaS 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 MaaS gateway error-code set.

Suggested debugging order

Check the HTTP status first to tell whether the failure is a stable MaaS gateway error or an upstream platform error.
Keep the X-Request-Id for support and log lookup.
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.
If the response is an upstream platform error, use error.type, error.code, and error.message to diagnose quota, auth, or platform policy issues.

Interface Guide

API Endpoints

Usage Examples

Error response shape

Error sources

MaaS gateway

Upstream platform errors

Suggested debugging order

​Error response shape

​Error sources

​MaaS gateway

​Upstream platform errors

​Suggested debugging order

Error response shape

Error sources

MaaS gateway

Upstream platform errors

Suggested debugging order