NUWAY API

Errors and rate limits

Errors

Errors return an HTTP status and a JSON body with detail. detail is either a message:

{ "detail": "Conversation not found" }

or, for billing problems, an object with a machine-readable error:

{ "detail": { "error": "insufficient_balance", "message": "..." } }

or, for invalid input, a list of the fields that failed:

{ "detail": [ { "type": "missing", "loc": ["body", "message"], "msg": "Field required" } ] }

Status	Meaning
`200` / `201`	Success / created.
`401`	Missing, invalid or revoked API key.
`402`	Payment required: out of chat credit, or the knowledge base needs more storage than your plan and wallet cover. See Usage limits and billing.
`403`	The resource belongs to another company.
`404`	Not found, or not yours.
`409`	Your account setup isn't finished. Complete it in the dashboard.
`413`	Uploaded file is too large (max 100 MB).
`422`	Invalid input. `detail` says what is wrong.
`429`	Rate limit exceeded, or too many invalid keys. Respect `Retry-After`.
`502`	The AI could not produce a reply this time. Safe to retry.

60 requests per minute per company, across all endpoints. The count resets at the start of each minute.
Above the limit you get 429 Too Many Requests with a Retry-After header (seconds). Wait, then retry.
Need more? On the API Key page, request a higher limit: the number of requests per minute you need (up to 6,000) and what it is for. Our team reviews requests and the page shows the outcome. An approved limit stays in place when you regenerate your key.
After 20 invalid keys within 5 minutes from one address, that address gets 429 for 5 minutes.

Retry 429 after the number of seconds in Retry-After, and 502 (the AI could not produce a reply this time).
Don't retry 401, 402, 403, 404, 409, 413 or 422 without changing something first: fix the key, the input, or the account.
Show the message of a 402 insufficient_balance error to your customer if you like: it is written for them. See Usage limits and billing.
Log the status and detail of every failed request.

See Troubleshooting for common problems.