Error responses say what to do next

The most common API errors now tell the caller how to recover, in optional fields at the top level of the body. Nothing was renamed or removed: error, code, status codes and headers are exactly what they were.

• A 401 names the credentials the API accepts in hint, and next lists where to get one: self-registration (while it is open) and the OAuth token endpoint.
• Agent management, agent keys and inbox, and approval decisions take a person's credential only. Sent a valid API key, they now answer 401 with their own message (it used to read only "Authentication required"), a hint that the route needs a dashboard session or a JWT, and an empty next, instead of pointing you at a new key. Approval decisions say so before checking scopes, so a key is never told to fetch a scope that still would not let it in.
• A 403 for a new key wider than the calling token says to ask only for scopes that token holds.
• A 400 for a body that fails validation lists each failing field in issues, with its path and the reason, plus a hint. Price computation, batch computation, price verification, function registration and agent self-registration also return example, a minimal body that passes.
• A body that is not JSON answers code: invalid_json with a hint on price computation, batch computation, price verification, function registration, API key and embed token creation, costs, credits, customers, disputes, invoices, orders, payments, pricing models, routing policies, webhooks, usage outcomes, data contributions and marketplace listings. Batch computation, price verification, function registration, costs, credits, customers, disputes, invoices, data contributions and new marketplace listings used to answer 500 here. The agent manifest lists the exact operations; other routes are unchanged.
• A 429 from the general rate limits carries retry_after (always equal to the Retry-After header) and limit. A daily quota says it is one: it resets after retry_after seconds, and the response names the ways past it sooner. A self-registered agent's daily limit carries the same hint, retry_after and limit, and its next is a list of steps like every other next: a pay_per_call step where the call can be paid for, and a claim step.
• A 403 insufficient_scope keeps required_scopes and adds a hint on how to get a key that carries the scope.

The agent manifest, llms.txt and the OpenAPI contract list the new fields. For help, write to support@last-price.ai.