A refused call answers with an HTTP status and, in most cases, a code and an error sentence. Find the code
below. The full answer bodies are in the API reference.
Money
| Status | code | What it means | What you do |
|---|---|---|---|
402 | budget_exceeded, budget_paused | A spending limit stops the job: the month's budget, a feature cap, or this key's limit. | Raise the limit on https://www.linkio.com/billing#limits, or wait for the next month. |
402 | needs_approval | The job costs more than your "ask me before any job over $X" amount. | Approve it on https://www.linkio.com/account/activity?view=waiting, then repeat the call once. |
402 | card_required | No money on the account covers the job, and there is no card. | Add a card on https://www.linkio.com/billing, add money on https://www.linkio.com/shop, or add your own provider keys on https://www.linkio.com/account/ai-keys. |
402 | payment_failed | The last card charge failed. Paid work is paused. | Change the card on https://www.linkio.com/billing. |
402 | credit_line | Unbilled usage reached the card's limit and is charged shortly. | Wait for the charge, or charge it now (usage_billing_pay_now). |
400 | CONFIRM_REQUIRED | A paid prospecting start needs your confirmation. Nothing is held. | Read the quote, then repeat the call with confirm: true. |
503 | TENANT_RESOLUTION_TIMEOUT | Linkio could not confirm in time who pays. No job started. | Repeat the same call once after Retry-After seconds. |
Keys and limits
| Status | code | What it means | What you do |
|---|---|---|---|
401 | No key, or the key is revoked or expired. | Make a key on https://www.linkio.com/account/api-keys. | |
403 | SCOPE_DENIED | The key does not hold the scope the call needs (required_scope). | Make a key with that scope, for example the Automation level, and revoke the old one. |
403 | ACCOUNT_TYPE_DENIED | A managed account's key called a self-serve-only route, such as site search. | Nothing. The route is not for managed accounts. |
403 | owner_only | A key tried to make a key. | The account owner makes keys on https://www.linkio.com/account/api-keys. |
403 | email_not_verified | The account's email is not verified. | Verify the email first. |
429 | DAILY_READ_CAP | The key used its reads for this UTC day. | Wait for resetsAt. Read less often: one feed read an hour is enough. |
429 | RATE_LIMIT_EXCEEDED | Too many MCP calls in a minute. | Wait Retry-After seconds. |
Closing, reopening and moving a placement
These come from line_item_close, line_item_reopen and line_item_replace_site. See
When a placement goes wrong.
| Status | code | What it means | What you do |
|---|---|---|---|
403 | NOT_SELF_SERVE | The placement is on a managed order. | Your account manager handles managed orders. |
400 | REASON_REQUIRED | The reason is missing or shorter than 5 characters. | Say why, for example "seller rejected: need a new site". |
409 | ALREADY_CLOSED | The placement is already cancelled, refunded or credited. | Nothing. Reopen it with line_item_reopen if you closed it. |
409 | ORDER_CLOSED | The order is completed or cancelled. | Nothing on it changes here. Ask Linkio, or add the site to a new order. |
409 | LIVE | The placement has a published URL. | Ask Linkio if the link is wrong or gone (report_issue). |
409 | LIVE_OR_PAID | The seller sent a published URL, or is paid or being paid. | Check the link and pay as usual. Ask Linkio for anything else. |
409 | SELLER_PAID | A seller invoice is paid, part paid, disputed or refunded. | The money must be settled first. Ask Linkio. |
409 | ORDER_PAID | The order was paid through Linkio. A self-serve order is never paid as a whole, so this is not one. | Ask Linkio. |
409 | CHECKOUT_OPEN | A payment through Linkio is open on the order. A self-serve order is never paid as a whole, so this is not one. | Ask Linkio. |
409 | EXCHANGE_ITEM | The placement is part of an exchange; other placements depend on it. | Ask Linkio to close or move it. |
409 | NOT_CLOSED | You asked to reopen a placement that is not closed. | Nothing. |
409 | NOT_CLOSED_HERE | Linkio cancelled this placement; it was not closed with line_item_close. | Ask Linkio. |
400 | TOKEN_REQUIRED | A move needs an offerToken. | Call line_item_replace_site with the domain and no token to list the sellers. |
400 | DOMAIN_INVALID | The domain is not a valid site. | Pass a domain like example.com. |
409 | SITE_ALREADY_USED | Another open placement of the same brand is on that site. | Pick a site that is new to the brand. |
400 | OFFER_NOT_FOUND | The token is not one of the site's sellers now. | List the sellers again. |
400 | OFFER_NOT_SELECTABLE | That seller cannot be chosen now. | Pick another seller. |
409 | SAME_SELLER | That seller is already on the placement. | Pick another seller or another site. |
Recording a publisher payment
| Status | code | What it means | What you do |
|---|---|---|---|
409 | ITEM_CLOSED | The placement is closed, so it is not marked paid. Its seller was told to stop. | If the seller did publish it, reopen it first (line_item_reopen), or ask Linkio. |
Articles
| Status | code | What it means | What you do |
|---|---|---|---|
409 | OWN_CONTENT | The placement is marked as your own article, so no AI article starts on it. | Upload your article with order_byoc_upload. Or clear the choice: ownContent: false with line_items_update. |
Connecting an agent
| Answer | What it means | What you do |
|---|---|---|
401 Missing Authorization header | The client sent no key. | Add the header Authorization: Bearer <your key>. |
403 Invalid API key, with a hint about a placeholder | The client sent the variable name, not the key. | Export the variable before you start the client, or write the key into the header. |
403 Invalid API key, Unrecognized credential format | The value is not a Linkio key. | Copy the key again from the keys page. |
Something else
A refusal that is not on this page, or a tool that does not do what it says: tell Linkio. An agent uses
report_issue (what it tried, what happened, what it expected; no secrets). report_status shows the team's
answer.