> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apigo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Error code guide inside API Guide for narrowing down request failures quickly.

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.

```json Example response theme={null}
{
  "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.

```json Platform passthrough example theme={null}
{
  "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

1. Check the HTTP status first to tell whether the failure is a stable MaaS 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.