# MyRadar API errors and recovery: bearer_required, plan_required

MyRadar's agent storefront answers credential, plan and purchase errors itself, as JSON with the code in `error`, and passes MyRadar's API's own status and body through once a call is forwarded. Fix the first kind by re-authenticating or buying a plan, and the second by fixing the request. Every call draws on a plan bought with an agent credential the storefront issues, and Credits start at $0.02 on a wallet rail or $0.50 by card.

## At a glance

- **Error format:** JSON whose `error` field names the code, sometimes refined by `reason` or `settlementReason`, sometimes with a human-readable `detail` note.
- **Storefront layer:** `401 bearer_required` (no credential), `401 invalid_token` (the credential did not verify), `403 plan_required` (no plan covers the call), plus purchase-amount and payment codes.
- **API layer:** MyRadar's own status code and body after the call is forwarded. The layers, severe weather and road weather time series operations list a `422` whose `detail` array locates the bad parameter. Forecast lists no `422`.
- **Base URL and header:** `https://agents.myradar.dev/zcj/kpl8mwfbul84`, with `Authorization: Bearer <token>` on every call.
- **Price per call on Credits:** Forecast $0.02 per 100 requests, Road weather time series $0.02 per 100 requests, Severe weather $0.02 per 100 requests, Radar and weather layers $0.02 per 100 requests.
- **Payment:** only a plan purchase answers with a 402, the price quote you pay and retry. It settles over x402 or MPP, the USDC wallet rails, or by card.
- **Retry unchanged:** among payment errors, only `payment_provider_unavailable`, with backoff.
- **Full purchase flow:** [buyer skill](https://agents.myradar.dev/zcj/kpl8mwfbul84/SKILL.md)

## Which layer answered

| Response | Layer | Recovery |
| --- | --- | --- |
| `401 bearer_required`, `401 invalid_token` | Storefront: credential | Register or refresh the token, then retry |
| `403 plan_required` | Storefront: plan | Buy a plan that covers the call, then retry |
| `400` or `404` on a purchase or top-up | Storefront: purchase | Fix the amount or the plan id |
| `settlement_failed`, `payment_*` | Storefront: payment | See Payment errors below |
| `422` or any other status from a forwarded call | MyRadar's API | Fix the request |

An example call:

```bash
curl -sS "https://agents.myradar.dev/zcj/kpl8mwfbul84/v1/forecast/45.51,-122.68?units=si&exclude=minutely" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Without the header, the answer is `401 bearer_required`. With a credential that holds no covering plan, it is `403 plan_required`. With a covering plan, the response is MyRadar's forecast JSON with `currently`, `hourly`, `daily`, `alerts` and `flags`.

## Credential errors

| Code | Meaning | Action |
| --- | --- | --- |
| `bearer_required` (401) | The call or purchase carries no agent credential. A wallet cannot supply one. A purchase without a bearer gets this before any price is quoted. | Reuse a stored ZeroClick credential, or register at [auth.md](https://agents.myradar.dev/zcj/kpl8mwfbul84/auth.md). Retry with `Authorization: Bearer <token>`, or `ZC-Agent-Authorization: Bearer <token>` when paying over MPP. |
| `invalid_token`, `reason` `token_expired` or `token_invalid` | The access token is no longer valid | Exchange the stored assertion at `https://agents.myradar.dev/zcj/kpl8mwfbul84/oauth2/token` for a fresh token |
| `invalid_token`, `reason` `malformed_agent_authorization` | `ZC-Agent-Authorization` is malformed | Send exactly one `Bearer <token>` |
| `invalid_token`, `reason` `unrecognized_agent_credential` | `ZC-Agent-Authorization` held something other than a ZeroClick-issued token | Put only the agent token there. Payment credentials stay in `Authorization`. |
| `invalid_token`, `reason` `conflicting_agent_credentials` | Two different agent tokens were sent | Send one |
| `invalid_token`, `reason` `combined_authorization_unsupported` | `Authorization` held `Payment ..., Bearer ...` | Move the token to `ZC-Agent-Authorization` |
| `identity_invalid` | The identity proof did not verify | Sign a fresh challenge and retry |
| `invalid_grant` (token exchange) | The stored assertion expired or was revoked | For a claimed credential, refresh at `https://agents.myradar.dev/zcj/kpl8mwfbul84/agent/identity`, then exchange again. Otherwise register again. |
| `verified_email_required` (403) | The action needs an identity claimed with a verified email | Complete the claim step in [auth.md](https://agents.myradar.dev/zcj/kpl8mwfbul84/auth.md), exchange again, then resume |

A 401 is not evidence that you own no plan. After recovering the credential, list what you hold with `GET https://agents.myradar.dev/zcj/kpl8mwfbul84/agent/entitlements` before buying.

## Plan and credit errors

### plan_required (403)

With `reason` `access_not_found`, the credential holds no plan. With `reason` `not_included_in_plan`, the plan you hold lacks a meter the call uses, and `meters` names it. The body's `plans` array names just the plans that cover this call, and each carries a `purchase.url`. Buy one once with your bearer at `POST https://agents.myradar.dev/zcj/kpl8mwfbul84/plans/{planId}/purchase`, taking the URL from the body or [manifest.json](https://agents.myradar.dev/zcj/kpl8mwfbul84/manifest.json), then retry the call. Credits takes an `amountUsd`. Starter, Pro and Platinum are monthly plans that take no amount; their fees are in the catalog.

### access_not_found

Recover the identity that made the purchase. Then check existing and pending purchases with `GET https://agents.myradar.dev/zcj/kpl8mwfbul84/agent/entitlements` before deciding to buy. A plan belongs to the registered identity, not to the payment instrument.

### usage_exhausted

The plan has no credit left. Add more to Credits with `POST https://agents.myradar.dev/zcj/kpl8mwfbul84/extend`, your bearer and `{"amountUsd": "<whole-cent amount>"}` of at least $0.02. The top-up answers with one 402, like a purchase, and the new balance returns as `access.remainingCreditUsd`. `plan_not_extendable` means the plan takes no top-up; inspect the plan's renewal or purchase contract instead.

## Purchase amount and plan id errors

| Code | Meaning | Action |
| --- | --- | --- |
| `invalid_request` (400) | The body is malformed | Fix the JSON |
| `amount_required` (400) | A Credits purchase had no amount | Send `{"amountUsd": "<whole-cent amount>"}` |
| `amount_not_cent_increment` (400) | `amountUsd` is not whole cents | Round to whole cents |
| `amount_below_minimum` (400) | `amountUsd` is under `purchase.minimumUsd` | Send at least $0.02 for Credits |
| `amount_above_maximum` (400) | `amountUsd` is over `purchase.maximumUsd` | Buy up to the maximum now and top up later |
| `amount_below_card_minimum` (400) | The amount meets the plan's minimum but is under the card minimum | Send at least $0.50 for new Credits by card, or pay on a wallet rail |
| `seller_not_found` (404) | The host does not map to a seller | Use `https://agents.myradar.dev/zcj/kpl8mwfbul84` as the base URL |
| `plan_not_found` (404) | The plan id is unknown | Take the id from [manifest.json](https://agents.myradar.dev/zcj/kpl8mwfbul84/manifest.json) |

## Payment errors

| Code | Meaning | Action |
| --- | --- | --- |
| `settlement_failed` | The signed payment did not settle. `settlementReason` says why, such as `insufficient_funds`. | Fix the wallet, then resend the purchase from the start for a fresh 402 |
| `payment_incomplete` | The referenced payment has not finished | For a card, poll the `statusUrl` from the 402's `card` block until it reports complete, then retry |
| `payment_unknown` | The reference matches no payment available to you here | Verify the payment id. A reference from an old challenge needs a new 402 from a fresh request. |
| `payment_consumed` | The payment was already settled | Confirm whether the original purchase was delivered before you ask for a new 402 or pay again |
| `payment_refunded`, `payment_failed`, `payment_released` | Terminal for that reference | Reconcile through its documented status route. With no outcome check, stop with an unknown outcome. Do not repay. |
| `payment_provider_unavailable` | Transient failure reaching the payment provider | Retry unchanged, with backoff |

Nothing is charged until you pay a purchase or top-up 402. After a timeout on a payment, check entitlements before paying again.

## Errors from MyRadar's API

### 422 validation error

The API reference lists `422` for every layers, severe weather and road weather time series operation except listing layers. The body is a `detail` array. Each entry carries `loc` (where the bad value is), `msg` and `type`, and sometimes `input` and `ctx`. Fix the value at `loc` and retry.

| Parameter | Accepted form |
| --- | --- |
| `point` (forecast path) | `lat,lon` with no space, such as `45.51,-122.68` |
| `latlons` | JSON array of `[lat, lon]` pairs, such as `[[41.5,-105.1]]`, URL-encoded once |
| `latlon` (severe history) | `lat,lon`, such as `41.5,-105.1` |
| `itime`, `depart_time`, layer point `valid_time`, history `begin_time` and `end_time` | `YYYYmmdd.HHMM`, such as `20250101.0000` |
| `cycle_time`, `image_time` (tiles) | `YYYYmmddHHMM` |
| `units`, `lang`, `extend` (forecast) | `us`, `si`, `ca` or `uk2`; `en`; `hourly` |
| `layer` | A name from `GET https://agents.myradar.dev/zcj/kpl8mwfbul84/v1/layers/listlayers` |

Service slugs such as `forecast` are never request values.

### Other status codes

Once a call is forwarded, you receive MyRadar's own status code and body. Check the operation's contract in [openapi.json](https://agents.myradar.dev/zcj/kpl8mwfbul84/openapi.json), honour any retry hint and keep retries bounded.

### zc-usage-error and zc-billing headers

A `zc-usage-error` header, such as `invalid_usage_header`, means the storefront could not bill an otherwise served response. You have the response, so do not retry. A plan-funded response carries `zc-billing` with `fundingSource`, `chargedUsd` and `remainingCreditUsd`.

## Frequently asked questions

### Why does a call answer 401 bearer_required when I have a wallet?

MyRadar calls are sold on plans, not per call, so a call never answers with its own price. Every call needs an agent credential registered with the storefront, and a wallet does not provide one. Register once at [auth.md](https://agents.myradar.dev/zcj/kpl8mwfbul84/auth.md), buy a plan with that credential, then send the call with `Authorization: Bearer <token>`.

### Why do I get plan_required right after buying a plan?

List what the calling identity holds with `GET https://agents.myradar.dev/zcj/kpl8mwfbul84/agent/entitlements`; a plan belongs to the identity that bought it, not to the payment. A card purchase must report complete at its `statusUrl` before the credit is usable. With `reason` `not_included_in_plan`, the `meters` field names what the plan lacks.

### How do I recover from usage_exhausted?

Top up Credits with `POST https://agents.myradar.dev/zcj/kpl8mwfbul84/extend`, your bearer and a whole-cent `amountUsd` of at least $0.02, then pay its 402 and retry the call. If the answer is `plan_not_extendable`, inspect the plan's renewal or purchase contract instead.

### Is a 422 a storefront error?

No. A `422` comes from MyRadar's API after the call was forwarded, and the API reference lists it for the layers, severe weather and road weather time series operations. It means a parameter is missing or malformed. Read `loc` in the `detail` array, fix that value and retry. Re-authenticating or buying does not change it.

### Which errors are safe to retry unchanged?

Among payment errors, only `payment_provider_unavailable`, with backoff. Every other payment code needs a fixed wallet, a fresh 402 or a reconciliation first.

## Keep reading

- [Buyer skill](https://agents.myradar.dev/zcj/kpl8mwfbul84/SKILL.md): the full purchase and recovery flow
- [Error reference](https://agents.myradar.dev/zcj/kpl8mwfbul84/errors.md): every storefront code
- [Agent identity](https://agents.myradar.dev/zcj/kpl8mwfbul84/auth.md): register, exchange, refresh and claim
- [How to pay](https://agents.myradar.dev/zcj/kpl8mwfbul84/payment.md): rails, plans and top-ups
- [Catalog](https://agents.myradar.dev/zcj/kpl8mwfbul84/manifest.json): live plans, prices and purchase URLs
- [API reference](https://agents.myradar.dev/zcj/kpl8mwfbul84/openapi.json): every operation and its parameters

---

Updated 2026-10-16. All MyRadar guides: https://agents.myradar.dev/guides.md. Storefront: https://agents.myradar.dev/zcj/kpl8mwfbul84/llms.txt.