# MagnetAPI.org RapidAPI Troubleshooting

Keep the `X-MagnetAPI-Request-ID` response header when contacting support. It
identifies request metadata without storing or exposing the prompt or response.

## All endpoints

- `401`: Check that the request uses the RapidAPI host, `X-RapidAPI-Key`, and
  `X-RapidAPI-Host`. Do not send a MagnetAPI System Token through RapidAPI.
- `403`: The RapidAPI subscription is inactive or the selected endpoint is not
  included in the subscribed plan.
- `429`: The RapidAPI API Token quota is exhausted. Review the RapidAPI billing
  page or select a larger plan when one is available.
- `502`: A model returned an empty, malformed, or interrupted response. Keep the
  request id and retry the same idempotent request.
- `503` or `504`: The service is temporarily unavailable or timed out. Check the
  public RapidAPI service-status page before retrying with exponential backoff.

## `GET /v1/models`

Use the exact model id returned in the `id` field. `magnetapi-sandbox` is a
non-billable integration model available only through RapidAPI.

## `POST /v1/responses`

Send either a string `input` or a valid Responses input-item array. Tool
definitions must use valid JSON Schema. Avoid unsupported regular-expression
lookarounds in schema `pattern` fields.

For streaming, set `stream: true` and process Server-Sent Events until
`response.completed`. Do not parse the stream as one JSON document.

## `POST /v1/chat/completions`

Send a `messages` array. Each message needs a valid `role`. Image inputs must
use the OpenAI-compatible content-part format. Tool results must reference the
matching tool call id.

## `POST /v1/messages`

Include `anthropic-version: 2023-06-01`, `max_tokens`, and a `messages` array.
For streaming, process events until `message_stop`. An HTTP 200 without a
content block is treated as an upstream error and is never returned as success.

## Token and trial headers

- `X-MagnetAPI-API-Tokens-Charged`: API Tokens charged for this call.
- `X-MagnetAPI-API-Tokens-Used-Period`: API Tokens used in the current UTC month.
- `X-MagnetAPI-API-Tokens-Remaining-Estimate`: local estimate against the
  50-token plan. RapidAPI remains authoritative for billing-cycle enforcement.
- `X-MagnetAPI-Trial-Status`: `not_started`, `active`, or `expired`.
- `X-MagnetAPI-Trial-Seconds-Remaining`: trial seconds remaining.
- `X-MagnetAPI-Latency-MS`: total MagnetAPI gateway latency for the request.

## Safe retry guidance

Retry `429`, `502`, `503`, and `504` responses with exponential backoff and
jitter. Reuse your application-level idempotency key for operations that create
stored objects. Do not retry authentication or validation errors without first
correcting the request.