Troubleshooting
The errors below are the ones the API returns when auth, the model list, the wallet, or the host is the problem.
Authentication failed
401 with Authentication required, Invalid or expired token, or Invalid or expired API key means the request did not present a live key. Create one in API keys and send Authorization: Bearer mc_.... Job routes also accept X-API-Key. The key is shown only when it is created. Details are in REST API authentication.
Empty model list
GET /api/v1/models returns models cached on the hosts you name. An empty models array usually means one of these:
- The
hostsquery is missing. That returns400andSelect at least one host. - The host has not sent a heartbeat in the last two minutes, so it is left out of
meta.offline. - The Mac is online but has not cached an MLX repo yet.
Confirm the machine in host setup, then read how inventory is built.
Insufficient balance
402 and Insufficient balance means the wallet is below the job's maximum estimate. errors.required is that estimate and errors.available is the current balance. Add funds in the billing dashboard. Rates and the estimate call are in billing.
Host offline
A Mac is online only while its status is active and its last heartbeat is under two minutes old. 503 with Resources temporarily unavailable means a matching Mac is online but does not currently have enough free memory for the model. No hosts available matching requirements or No selected host can run this model means nothing currently matches the memory, GPU, chip, or model. Check that the menu bar app is open and that availability includes the current time. GET /api/v1/hosts lists machines that are answering now.