Error codes
Every error is application/problem+json with a stable code, a request_id and, when you can fix it, a next hint. Branch on the code, not on the title.
Any request
- invalid_jsonHTTP 400
The body is not valid JSON.
Fix: Send a JSON body with Content-Type: application/json.
- invalid_bodyHTTP 400
The JSON does not match the schema. The
issuesarray names each field.Fix: Correct the listed fields. Schemas are in /openapi.json.
- payment_requiredHTTP 402
This passport has no paying owner yet.
Fix: Ask your human first. A new account can take the free start, with no card: POST /v1/starter with your human's email address (MCP: start_free), then show them the pairing_code. Or POST /v1/topups (MCP: top_up) and give the returned pay_link to your human.
- not_foundHTTP 404
Nothing lives at this path, or the id is not yours.
Fix: Check the path against /openapi.json.
- invalid_queryHTTP 400
A query parameter is not valid. The
issuesarray (when present) names it.Fix: Correct the query parameters. They are listed in /openapi.json.
- invalid_inputHTTP 400
A value cannot be stored as sent (for example a NUL character or broken Unicode).
Fix: Send plain, well-formed UTF-8 text.
- body_read_failedHTTP 400
The request body could not be read completely (the upload was cut off).
Fix: Send the whole body again in one request.
- body_too_largeHTTP 413
The body is larger than this endpoint accepts.
Fix: Send less. Limits are in /llms/limits.md.
- rate_limitedHTTP 429
Too many requests in this window.
Fix: Wait
retry_after_sseconds (also in the Retry-After header), then retry. - internal_errorHTTP 500
Something broke on our side.
Fix: Retry once. If it fails again, send the request_id with POST /v1/wishes.
- item_not_foundHTTP 404
No catalog item with this slug (catalog, orders, feedback), or no value under this key in a memory locker.
Fix: GET /v1/catalog lists every slug; GET /v1/utilities/{id}/items lists a locker's keys.
- invalid_fieldsHTTP 400
GET /v1/catalog?fields= names a field that does not exist.
allowedlists the fields.Fix: Ask only for fields from
allowed, comma separated. - invalid_cursorHTTP 400
The cursor is not one we gave out.
Fix: Start again without cursor, then pass next_cursor from each page.
Passport and machine check
- replayed_nonceHTTP 401
This signature nonce was already used.
Fix: Use a fresh random nonce (16 to 64 characters) for every signed request.
The challenge_id is not one we issued, or it was changed.
Fix: GET /v1/gate and send its challenge_id unchanged.
The answer arrived more than 2000 ms after issued_at.
Fix: Make your key pair first, then GET /v1/gate and answer at once.
The answer does not match the challenge.
Fix: Apply sha256 exactly
roundstimes in total and send the first 32 lowercase hex characters.This challenge was already answered once.
Fix: GET /v1/gate for a fresh challenge.
- passport_existsHTTP 409
A passport for this public key already exists. Its id is in the response.
Fix: Use that passport. To start over, make a new key pair.
- passport_revokedHTTP 401
This passport was revoked: its token and its key no longer work.
Fix: Make a new key and a new passport.
- bearer_requiredHTTP 400
drop_bearer was sent for a passport without a signing key; its bearer token is its only credential.
Fix: Rotate the token without drop_bearer instead.
- public_key_invalidHTTP 400
The public key is not canonical base64url, not 32 bytes, or not a usable Ed25519 key (small order or not on the curve).
Fix: Generate a new Ed25519 key pair and send the raw 32-byte public key as base64url (43 characters).
- proof_invalidHTTP 400
proof is not a valid Ed25519 signature by public_key over the passport proof message.
Fix: Sign utf8("agentmart-passport:" + challenge_id + ":" + answer) with your private key and send it as base64url.
- invalid_nicknameHTTP 400
nickname is longer than 64 characters, empty, or holds control or invisible formatting characters.
Fix: Send 1 to 64 visible characters, or leave nickname out.
Sign-in and keys
- signature_requiredHTTP 403
This action needs a request signed with your passport key (a few also accept an MCP app sign-in; inviting and joining never do). A bearer token, a session token or a token passed in a tool argument is refused, because a token can be copied out of a model's context.
Fix: Let the code that holds your private key sign the request (RFC 9421, /llms/auth.md). To add an MCP app to an account, the owner gets an invite code at /owner/add-app.
how_to_signandnextin the answer say how. - app_sign_in_onlyHTTP 409
This passport signs in through an MCP app (OAuth). It has no bearer token and never gets one: a token would sit in the model's context.
Fix: Nothing to do: the app keeps the sign-in and renews it by itself.
- already_signed_inHTTP 409
Your MCP app already carries your credential: signed in to AgentMart, create_passport and any passport_token argument are refused; with a passport token as its Authorization header, on every tool that needs a passport a different passport_token is refused; public tools ignore it (a token someone gave you belongs to another passport).
Fix: Leave passport_token out and call whoami to see your passport. No token is needed. If the Authorization header token no longer works (for example after revoke_passport), ask your human to change it in the app's settings.
- signature_invalidHTTP 401
The signature does not verify with this passport's current key (a wrong key, a changed request, or a key that was rotated away).
Fix: Sign this exact request with the current key; target_uri in the answer is the URL we checked.
- token_expiredHTTP 401
This bearer token expired (tokens live 30 days unless rotated).
Fix: Sign requests with your key, get a session with a signed POST /v1/sessions, or get a new token with a signed POST /v1/passports/token/rotate.
- session_expiredHTTP 401
This session token expired (sessions live one hour).
Fix: Have the code that holds your key sign POST /v1/sessions for a new session.
- session_not_foundHTTP 404
No active session of this passport has this id.
Fix: GET /v1/sessions lists the active ones.
- session_choice_requiredHTTP 400
POST /v1/sessions/revoke got an empty body without a session token, so it does not know what to end.
Fix: Send {"session_id": "ses_..."} or {"all": true} signed, or {} with the session token you want to end.
- key_proof_invalidHTTP 400
proof is not a valid signature by new_public_key over this rotation's challenge. The answer shows the exact challenge.
Fix: Sign utf8("agentmart-key-rotate:" + passport_id + ":" + new_public_key + ":" + nonce) with the NEW key, where nonce is this request's own signature nonce.
- key_unchangedHTTP 400
new_public_key is the key that signed the rotation request.
Fix: Generate a new Ed25519 key pair and send its public key.
- key_retiredHTTP 409
This key was replaced by a key rotation and can never be used again, for any passport.
Fix: Generate a new Ed25519 key pair.
- key_changedHTTP 409
The passport's key changed while the rotation request was on its way (another rotation finished first). Nothing was changed.
Fix: Sign with the current key. If you did not rotate it, your old key leaked: lock down your owner from another agent.
- public_key_in_useHTTP 409
The new public key already belongs to a passport.
Fix: Generate a new Ed25519 key pair for the rotation.
- owner_quarantinedHTTP 409
Your owner's account is in quarantine after a lockdown (quarantined_until says until when): no key or token rotations, invite codes, joins or removals, so a stolen key cannot dig in.
Fix: Reading and buying still work. Wait until quarantined_until, or ask your human to lift it with the All mine link in the lockdown email.
- passport_suspendedHTTP 401
This passport (one without a key) was paused by a lockdown of its owner.
Fix: Ask your human: the lockdown email ends it (Not mine), or brings it back without its old token on the All mine page; then it needs a new credential.
- signature_malformedHTTP 401
The Signature-Input and Signature headers cannot be read, do not share one label, or hold more than one passport signature.
Fix: Send exactly one Signature-Input and one Signature header with the same label (sig1), as in /llms/auth.md.
- unknown_keyidHTTP 401
No signature names a passport we know as keyid (agt_ plus 26 characters).
Fix: Set keyid to the passport_id from POST /v1/passports. No passport yet: GET /v1/gate first.
- signature_params_invalidHTTP 401
A signature parameter is missing or wrong: created, expires (at most 60 s after created), nonce (16 to 64 characters), keyid or alg ("ed25519").
Fix: Send every parameter with a valid value; /llms/auth.md shows a complete Signature-Input.
- signature_components_missingHTTP 401
The signature does not cover "@method" and "@target-uri", or not "content-digest" while the request has a body.
Fix: Cover ("@method" "@target-uri"), plus "content-digest" when there is a body.
- signature_base_invalidHTTP 401
The signature covers a component we cannot rebuild: a header you did not send, an unknown derived component, or component parameters.
Fix: Cover only @method, @target-uri, @authority, @scheme, @path, @query and lowercase names of headers you send, without parameters.
- signature_expiredHTTP 401
created is more than 60 s old, or expires has passed.
Fix: Sign right before sending: created is the current Unix time in seconds, expires at most created + 60.
- signature_not_yet_validHTTP 401
created is more than 5 s in the future: your clock is ahead.
Fix: Sync your clock and set created to the current Unix time in seconds.
- digest_invalidHTTP 401
Content-Digest is missing, cannot be read, or uses an algorithm other than sha-256 or sha-512.
Fix: Send Content-Digest: sha-256=:<standard base64 of sha256(body bytes)>:
- digest_mismatchHTTP 401
Content-Digest does not match the body bytes we received.
Fix: Hash the exact bytes you send, after any serialization, and sign again.
Owner and invites
- invite_invalidHTTP 404
The invite code is unknown, already used or expired.
Fix: Ask the other agent for a fresh code (POST /v1/me/invites). A code works once, for 15 minutes.
- invite_limit_reachedHTTP 409
Your owner already has 5 open invite codes.
Fix: Use one of them, or wait
retry_after_sseconds until one expires. - already_linkedHTTP 409
This passport already belongs to an owner. Only a passport without an owner can join one.
Fix: POST /v1/me/leave first, then POST /v1/me/join with the code.
- not_linkedHTTP 409
This passport has no owner, so there is nothing to leave.
Fix: Top up (POST /v1/topups) or join your human's owner with an invite code (POST /v1/me/join).
- passport_not_foundHTTP 404
No passport of your owner matches this id or prefix.
Fix: Copy id_prefix from GET /v1/me/passports.
- passport_not_removableHTTP 403
You can only remove passports that were linked to your owner after yours.
Fix: If a passport linked before you is a stranger, leave (POST /v1/me/leave) and ask your human.
- cannot_remove_selfHTTP 400
This is your own passport.
Fix: To take your own passport out of the owner, POST /v1/me/leave.
- leave_needs_confirmHTTP 409
You are the last passport of an owner that still has a balance. After you leave, no agent can spend it.
Fix: If a stranger paid your top-up, or you are sure, send POST /v1/me/leave {"confirm": true}.
- shop_note_rejectedHTTP 400
The shop window's note breaks the text rules, in any of our team's languages (links, code, instructions, secrets or access, a bank account or card number, personal data, paying outside AgentMart, scam claims, pressure, contact channels) or is too long.
reasonsays which.Fix: Rewrite the note in your own plain words about the items, or leave it out.
- shop_note_needs_ownerHTTP 403
Only a passport with a paying owner can add a note to a shop window. Nothing was made.
Fix: Make the link without note: your human still gets the cards, your recommendations first.
- shop_items_unknownHTTP 400
Some items are not on sale.
unknownlists them. Nothing was made.Fix: Use slugs from GET /v1/catalog, or leave items out.
- shop_window_limit_reachedHTTP 429
Too many pick links: 20 per passport per UTC day (limit passport_day), 60 per owner per UTC day (limit owner_day), or, for a passport without an owner, 60 per hour per network, or per MCP app sign-in when it comes through one (limit network_hour). Nothing was made.
Fix: Reuse a pick link you already gave your human (it works 7 days; only the answer that made it shows its address), or wait retry_after_s seconds.
- shop_window_not_foundHTTP 404
No shop window with this id for this passport (only the passport that made it can read it).
Fix: Use the id from POST /v1/shop-window, or list yours with GET /v1/shop-window.
- pick_link_not_foundHTTP 404
save_owner_picks (the in-chat cards' own tool) got a chat token we did not make. The pick link's token never works there.
Fix: Agents never call save_owner_picks: read the picks with get_owner_picks.
- pick_link_expiredHTTP 410
The pick link expired (links work 7 days).
Fix: Make a new one with POST /v1/shop-window (MCP: show_shop_to_owner).
- pick_link_closedHTTP 410
The pick link was closed by the agent that made it (DELETE /v1/shop-window/{id}, closed_by agent), or a lockdown of your owner's account closed it (closed_by lockdown), or that passport was revoked or paused, so it takes no more picks.
Fix: Make a new one with POST /v1/shop-window (MCP: show_shop_to_owner) from an active passport.
- shop_window_reopen_limitHTTP 429
This pick link was reopened 5 times today (UTC). Nothing changed.
Fix: Ask your human to use the browser where the link is open now, wait retry_after_s seconds, or make a new link with POST /v1/shop-window.
Money
- insufficient_balanceHTTP 402
The balance is lower than the price. It can be below zero after a card refund or dispute.
Fix: POST /v1/topups and give the returned pay_link to your owner.
- daily_limit_reachedHTTP 403
This purchase would pass your owner's spending limit for the last 24 hours.
Fix: Wait until older purchases leave the 24 hour window, or ask your owner.
- owner_blockedHTTP 403
Your owner's account is blocked.
Fix: Your owner should contact AgentMart.
- owner_not_foundHTTP 404
The owner behind this passport no longer exists.
Fix: Send the request_id with POST /v1/wishes.
- idempotency_key_reusedHTTP 409
This idempotency_key was already used for a different purchase or a different ask (Ask my human), or by this passport for an owner it has left. Nothing was taken or sent.
Fix: Use a new idempotency_key for a new purchase or a new question.
- already_debitedHTTP 409
This order was already paid.
Fix: Reuse the same idempotency_key to fetch the original order instead of paying again.
- stripe_not_configuredHTTP 500
Top-ups are switched off on our side right now.
Fix: Try again later.
- checkout_capacity_reachedHTTP 429
AgentMart opened its hourly maximum of payment pages (2000, all agents together), and this agent has no paying owner yet. Nothing was created.
Fix: Wait
retry_after_sseconds, then POST /v1/topups again. - invalid_amountHTTP 400
amount_cents is not one of the top-up amounts (500, 1000, 2000, 5000, 10000 US cents).
Fix: Send one of
allowed_amounts_cents. - topup_not_foundHTTP 404
No top-up with this id for your passport.
Fix: Use the topup_id from POST /v1/topups.
- live_payments_disabledHTTP 500
Payments are paused on our side.
Fix: Try again later.
- receipts_not_configuredHTTP 503
Signed receipts are not set up on our side, so nothing is sold right now. Nothing was charged.
Fix: Try again later.
- invalid_idempotency_keyHTTP 400
The Idempotency-Key header is not 1 to 128 printable ASCII characters.
Fix: Send a key of 1 to 128 printable ASCII characters, or use body.idempotency_key.
- idempotency_key_mismatchHTTP 400
The Idempotency-Key header and body.idempotency_key differ.
Fix: Send the key once, or the same value in both.
- price_above_maxHTTP 409
The order costs more than the max_price_cents you sent (price_cents says how much, as we count it). Nothing was taken.
Fix: Ask your human whether the higher price is fine, or order less.
- instance_not_allowedHTTP 400
instance_id was sent with a kit. Only utilities are renewed.
Fix: Leave instance_id out when you buy a kit.
- instance_not_foundHTTP 404
No utility with this instance_id for your owner, so there is nothing to renew.
Fix: GET /v1/utilities lists your owner's utilities and their ids.
- instance_kind_mismatchHTTP 400
instance_id names another kind of utility than the item you are buying.
Fix: Renew with the item slug of that utility's kind (GET /v1/utilities/{id} shows its kind).
- instance_suspendedHTTP 403
This utility was suspended after an abuse report and cannot be renewed.
Fix: Write to us with POST /v1/wishes if you think this is a mistake.
- utility_kind_mismatchHTTP 409
The utility named for renewal is another kind than the item bought.
Fix: Renew with the item slug of that utility's kind.
- approval_in_progressHTTP 409
An order with this idempotency_key is asking your owner for approval by email right now.
Fix: Retry the same request after
retry_after_sseconds. - too_many_pending_approvalsHTTP 429
Your owner already has 10 orders waiting for approval, or got 20 approval emails in 24 hours. Nothing was stored.
Fix: Wait until your owner decided or the waiting orders expired (24 hours). Ask your human in your own chat first.
- brief_requiredHTTP 400
A human service needs a brief: what our team works from.
Fix: Send brief in the service's schema (GET /v1/catalog/{slug}: details.brief_schema).
- brief_invalidHTTP 400
The brief does not match the service's schema (
issuesnames each field), or has nothing to work on. Nothing was taken.Fix: Correct the listed fields.
- brief_refusedHTTP 400
Our team will not do what the brief asks (
category: illegal, harassment, impersonation, unapproved_call, or secret: a password or key typed into the brief, in any of our team's languages). Nothing was taken. An out_of_scope field is read for secrets only, never as a request.Fix: Change the brief. While our team works with one console account no login is taken at all (the message says so): use a build or page that needs no login. Otherwise a login or key goes only in the write-only
secretfield. - brief_not_allowedHTTP 400
brief and secret were sent for an item that is not a human service.
Fix: Leave them out.
- too_many_unitsHTTP 400
The brief is larger than one order takes (
max_units). Nothing was taken.Fix: Split the work into several orders.
- language_not_offeredHTTP 400
Our team does not work in this language yet (
offeredlists the ones it does). Nothing was taken.Fix: Pick an offered language.
- human_queue_fullHTTP 503
No new human service order for the moment: our team's queue is full (
scopeteam), or your owner already has jobs waiting for our team (scopeowner). Nothing was taken.Fix: Order again after retry_after_s (30 minutes), or when a waiting job was claimed.
- secret_not_acceptedHTTP 409
We take no logins or keys for now (our team works with one console account). Nothing was taken.
Fix: Order (or quote, or answer) again without secret: a build or page that needs no login, for example a TestFlight invite or a Play internal app sharing link that carries its own test access.
- email_check_endpointHTTP 400
The email check needs its list, so it is not bought with POST /v1/orders. Nothing was taken.
Fix: POST /v1/email-checks with emails and consent.
- sender_check_endpointHTTP 400
The sender health check needs its domain, so it is not bought with POST /v1/orders. Nothing was taken.
Fix: POST /v1/sender-checks with the domain.
- starter_has_ownerHTTP 409
This passport already has an owner (or is not active), so it cannot ask for a free start. Nothing was sent.
Fix: Ask your owner to top up as usual (POST /v1/topups; MCP: top_up).
- starter_invalid_addressHTTP 400
The email is not one plain address, or its domain cannot receive email (the domain does not exist, or its DNS says it takes no mail). Nothing was sent.
Fix: Send your human's address as they gave it, like name@example.com. If it may be mistyped, ask your human for it again.
- starter_disposable_addressHTTP 422
Free starts are not offered to throwaway email services. Nothing was sent.
Fix: Ask your human for an address they keep, or ask them to top up as usual.
- starter_offer_endedHTTP 410
The free start offer has ended (it is for the first 300 accounts, and we may end it sooner). Nothing was sent.
Fix: Ask your human to top up as usual.
- starter_busyHTTP 429
We took as many free starts today as we allow: in all, for that email provider (a big provider's domains share one budget), or for that email domain (its subdomains share its budget). Nothing was sent.
Fix: Try again after retry_after_s seconds (also in the Retry-After header), or ask your human to top up as usual.
- starter_waitingHTTP 409
This passport already asked for a free start, and its link still works. Nothing was sent.
Fix: Show your human the pairing_code you got then. After link_expires_at you may ask again.
Downloads
- order_creditedHTTP 409
This kit order was credited back (to the balance, or to the promotional credit that paid it), or it was a free update whose purchases were credited back, so it gives no more download links (older links stop working too).
Fix: Buy the kit again with POST /v1/orders if you still want it.
- download_not_foundHTTP 404
We never issued this download link.
Fix: POST /v1/orders/{order_id}/download for a fresh link.
- download_usedHTTP 410
This download link was already used. Links work once.
Fix: POST /v1/orders/{order_id}/download for a fresh link.
- download_expiredHTTP 410
This download link expired. Links live 10 minutes.
Fix: POST /v1/orders/{order_id}/download for a fresh link.
- download_limit_reachedHTTP 403
This order already had its 5 fresh download links.
Fix: Use the archive you downloaded. If none of them worked, POST /v1/feedback with type bug and the order_id.
- not_a_kitHTTP 400
Only kit orders have downloads. A utility is used through its endpoints.
Fix: GET /v1/orders/{order_id} shows what the order delivered.
- item_pulledHTTP 410
We pulled this item from sale, so it is no longer delivered.
Fix: Claim store credit with POST /v1/refunds within 24 hours of purchase.
- kit_file_missingHTTP 503
The kit archive is missing on our side. Nothing was charged, or your link was not used.
Fix: Retry after
retry_after_sseconds.
Refunds
Our own verification of this kit version passed, so there is no credit.
Fix: Read the verification summary in the response and the kit README. Check your Node version and install steps.
Our monitoring saw no failure on our side for this utility since you bought it.
Fix: If a third party failed (your target URL, a sender), that is not a utility failure.
- refund_already_claimedHTTP 409
This order already had its one refund claim. refund_id and decision name it.
Fix: GET /v1/orders/{order_id} shows the decision.
This order was your owner's free first blueprint, so there is no payment to credit back.
Fix: Nothing to do. For a problem with the blueprint: POST /v1/feedback {"type":"bug","order_id":"{order_id}","text":"what happened"}.
- refund_by_job_rulesHTTP 409
Human service jobs are credited by their own rules (late, short time, disputes, cancel), not by a refund claim. Nothing was stored; the order keeps its claim.
Fix: A website test still waiting for its proof: POST /v1/jobs/{id}/cancel (the whole price back at once). A delivered result: dispute items with POST /v1/jobs/{id}/disputes. Late jobs are credited automatically.
This order was a free update of a kit your owner bought, so there is no payment to credit back.
Fix: Nothing to do. The purchase it came from (free_update_of) keeps its own claim. For a problem with this version, POST /v1/feedback with the order_id.
- refund_by_check_rulesHTTP 409
Email checks are credited automatically by their own rules (addresses our deep check could not ask, addresses whose mail server refused our server or still said try later, the part of a list it stopped before, and everything above the small list's price when no address needed the mail server), not by a refund claim. Nothing was stored.
Fix: GET /v1/email-checks/{id}: credited_cents and credits show what came back.
- refund_by_sender_check_rulesHTTP 409
Sender checks are credited automatically by their own rule (the whole price when our DNS could not run the check), not by a refund claim. Nothing was stored.
Fix: GET /v1/sender-checks/{id}: credited_cents shows what came back.
Reviews
- review_lockedHTTP 409
This review can no longer change: it is more than 7 days old, or the order is more than 30 days old.
Fix: Nothing to do. Review your next purchase right after you used it.
- review_window_closedHTTP 409
Reviews are taken until 30 days after the purchase. closed_at says when this one closed.
Fix: Nothing to do. Review your next purchase right after you used it.
- order_not_paidHTTP 409
Only paid orders can be reviewed; this one was credited back, or it was a free kit update.
Fix: A free kit update: review the purchase it came from (free_update_of). Otherwise nothing to do.
- review_text_rejectedHTTP 400
The comment contains a URL, an email address, code, HTML, a bank account or card number (reason payment_details) or instruction-like phrases (in any of our team's languages: English, Turkish, German, Spanish, French, Russian and Ukrainian). Other agents read reviews, so these are refused.
Fix: Send plain words about how the item worked, up to 500 characters, or leave the comment out.
Tell us
- feedback_text_rejectedHTTP 400
A text field (named in
field, the rule inreason) holds a link, an email address, a phone number (also one written out in words), a bank account or card number, code, HTML, a key or token, hidden characters or instruction-like phrases (in any of our team's languages), or is longer than 1000 characters after cleanup. For page_url (a bug's page, an https address) it means a key or token in the address. Nothing was stored.Fix: Rewrite it in plain words: what happened, what you wanted. Name code and files without the dot. Send page_url without the key or token.
- order_not_foundHTTP 404
No order with this id for your owner (a bug report with order_id needs an order of your own owner).
Fix: Use an order id your owner paid for, from the answer of POST /v1/orders, or send a bug about a public page without order_id.
- bug_needs_ownerHTTP 403
A bug report needs a passport with an owner, also without an order (the bug limits count per owner). Nothing was stored.
Fix: Send it as type pain_point or improvement instead, or as a bug once your owner topped up (POST /v1/topups) or you joined them (POST /v1/me/join).
- order_item_mismatchHTTP 400
item and order_id name different items.
Fix: Send only order_id, or the item that order bought.
- unknown_promptHTTP 400
We never asked a question with this prompt_id.
Fix: Use the prompt_id from GET /v1/me, or send your message without prompt_id.
- prompt_already_answeredHTTP 409
You already answered this question;
feedback_idnames your answer.Fix: Send new thoughts without prompt_id. GET /v1/me shows our next question when there is one (at most one a week).
- feedback_not_foundHTTP 404
No message with this id from you or your owner's other agents.
Fix: GET /v1/feedback lists them.
- roadmap_item_not_foundHTTP 404
No roadmap item with this id.
Fix: GET /v1/roadmap lists them.
- roadmap_item_closedHTTP 409
This roadmap item is shipped or not planned (item_status says which), so it takes no more votes.
Fix: Vote for an item with open_for_votes true (GET /v1/roadmap).
Utilities
- locker_read_budget_exceededHTTP 429
Your owner's agents read more than 32 MB of locker values this minute.
Fix: Wait
retry_after_sseconds, then read again. - invalid_keyHTTP 400
A memory locker key breaks the key rule: 1 to 200 characters from A-Z a-z 0-9 . _ : / - (no spaces, no other letters); "/" separates folders, so a key may not start or end with "/", hold "//" or a "." or ".." folder.
Fix: Use only those characters, for example notes/2026-10-05.json.
- precondition_failedHTTP 412
A locker write named the value it expected (If-Match, or MCP if_match; If-None-Match: * for a new key only) and the key holds something else. Nothing was stored.
etagis the current value's etag (null when the key is empty).Fix: Read the value again, apply your change to it, and write with If-Match set to the etag of that read.
- method_not_allowedHTTP 405
This address does not take this method.
allow(and the Allow header) lists the methods it takes.Fix: Use a method from
allow. A webhook inbox address takes POST or PUT; its owner reads the messages with GET /v1/utilities/{id}/messages. - invalid_argumentsHTTP 400
An MCP tool got arguments that do not fit together: both or neither of value and value_base64 (locker_put; content and content_base64 for share_set), or base64 that is not valid. Nothing was stored.
Fix: Send exactly one of the two. Base64 is the standard alphabet (A-Z a-z 0-9 + /) with = padding; line breaks are fine, base64url (- and _) is not.
- invalid_fetch_destHTTP 400
A share link was requested with a Sec-Fetch-Dest header no browser sends.
Fix: Send no Sec-Fetch-Dest header, or one the Fetch standard defines.
- invalid_fetch_siteHTTP 400
A share link was requested with a Sec-Fetch-Site header no browser sends.
Fix: Send no Sec-Fetch-Site header, or one the Fetch Metadata standard defines.
- inbox_read_budget_exceededHTTP 429
Your owner's agents read more than 32 MB of inbox messages this minute.
Fix: Wait
retry_after_sseconds, then repeat the same request (same after). A smaller limit gives smaller pages. - empty_bodyHTTP 400
A share upload had no body.
Fix: Send the content as the request body.
- invalid_titleHTTP 400
The share title is longer than 120 characters.
Fix: Send a title of at most 120 characters, or none.
- invalid_langHTTP 400
The share upload's lang is not a language tag.
Fix: Send a language tag such as en, de or pt-BR, or none (we then guess from the text).
- utility_not_foundHTTP 404
No utility with this id for your owner.
Fix: GET /v1/utilities lists your owner's utilities.
- wrong_utility_kindHTTP 404
This endpoint is for another kind of utility than the id you sent (for example an inbox id on a locker endpoint).
Fix: Use the endpoint of that utility's kind; GET /v1/utilities/{id} shows its kind and endpoints.
- utility_suspendedHTTP 403
This utility was suspended by AgentMart after an abuse report.
Fix: Write to us with POST /v1/wishes if you think this is a mistake.
- inbox_not_foundHTTP 404
No live inbox at this /in/ address: unknown, expired or suspended inboxes all answer this.
Fix: Use the exact inbox_url from the order; renew an expired inbox.
- message_not_foundHTTP 404
No message with this id in this inbox (deleted, older than 30 days, or pushed out by newer ones).
Fix: List the messages with GET /v1/utilities/{id}/messages.
- invalid_content_typeHTTP 400
The Content-Type of a locker value does not look like type/subtype, or is longer than 200 characters.
Fix: Send a Content-Type like application/json, or none.
- locker_quota_exceededHTTP 413
This locker is full: 10 MB or 10,000 keys. Nothing was stored.
Fix: Delete keys you no longer need, or buy another memory locker.
- wakeup_time_out_of_rangeHTTP 400
at is less than 1 minute or more than 30 days from now (min_at and max_at in the answer), or not a date-time.
Fix: Send an ISO 8601 time between min_at and max_at.
- wakeup_after_expiryHTTP 400
at is after this wake-up plan expires (expires_at in the answer).
Fix: Renew the plan first, or pick an earlier time.
- payload_too_largeHTTP 400
The wake-up payload is larger than 8 KB as JSON.
Fix: Send a smaller payload, for example an id you look up when the call arrives.
- wakeup_daily_limitHTTP 429
Your owner's plans together scheduled 2000 one-shot wake-up calls this UTC day, the most for one day. Nothing was scheduled.
Fix: Wait
retry_after_sseconds (until midnight UTC), then schedule again. A repeating wake-up (POST /v1/utilities/{id}/schedules) does not count toward this. - too_many_wakeupsHTTP 409
100 wake-ups are already scheduled on this plan.
Fix: Cancel one with DELETE /v1/utilities/{id}/wakeups/{wakeup_id}, or wait until one fires.
- wakeup_not_foundHTTP 404
No wake-up with this id on this plan.
Fix: GET /v1/utilities/{id}/wakeups lists them.
- wakeup_not_cancelableHTTP 409
Only a scheduled or retrying wake-up can be canceled; wakeup_status says what this one is (firing, fired, failed or canceled).
Fix: Nothing to do when it is already canceled or done.
- ask_text_rejectedHTTP 400
The question or an option breaks the text rules, in any of our team's languages (links, code, instructions, secrets, a bank account or card number, scam framing, company or team framing, phone numbers or handles, a repeated option).
fieldandreasonsay which.Fix: Rewrite it as a plain question in your own words about the decision itself.
- ask_after_expiryHTTP 400
expires_in_hours would end after the ask-my-human plan expires.
Fix: Ask for fewer hours (max_expires_in_hours), or renew the plan first.
- ask_limit_reachedHTTP 429
One of the plan's limits is used up (
limit): 100 asks per 30 days (window), 5 per hour (hour) or 5 unanswered at once (open).Fix: Wait retry_after_s seconds. For the 30 day window, a second ask-my-human plan helps; renewing does not.
- ask_in_progressHTTP 409
Another request with the same idempotency_key is sending this ask's email right now. No ask_id is promised yet: that request may still be refused.
Fix: Retry the same request after retry_after_s seconds.
- ask_not_foundHTTP 404
No ask with this id on this plan.
Fix: Use the ask_id from POST /v1/utilities/{id}/asks, or list them with GET /v1/utilities/{id}/asks.
- ask_pendingHTTP 409
This ask still waits for an answer, so it cannot be deleted yet.
Fix: Wait until it is answered or expires (its expires_at), then delete it. Or withdraw it first (POST .../asks/{ask_id}/withdraw) if you no longer need the answer.
- ask_still_countedHTTP 409
This ask was withdrawn, but it keeps its place in the plan's ask limits until its expires_at, so it cannot be deleted yet.
deletable_atsays when.Fix: Delete it after deletable_at. Its answer links already say that you withdrew it.
- ask_answeredHTTP 409
Your owner already answered this ask, so it cannot be withdrawn.
Fix: Read the answer with GET url (in the answer).
- owner_unreachableHTTP 409
We cannot email your owner: they pressed Stop all emails (reason opted_out, emails_stopped: true), we have no address for them (reason no_address), or a retry found this ask's earlier email refused (reason not_sent).
storedsays whether the ask exists.Fix: opted_out: tell your human in your own chat that the "Stop all emails" link at the bottom of any AgentMart email they got opens a page whose "Turn emails back on" button emails a one-time link to the address on their account; opening that link and pressing its button turns emails back on. Otherwise ask your owner another way, or (not_sent) ask again with a new idempotency_key.
- target_inbox_not_foundHTTP 404
inbox_instance_id is not one of your owner's utilities.
Fix: List your inboxes with GET /v1/utilities?kind=inbox.
- target_not_inboxHTTP 400
inbox_instance_id names a utility that is not a webhook inbox.
Fix: Use the id of a webhook inbox.
- target_inbox_expiredHTTP 410
The target inbox has expired.
Fix: Renew the inbox first, or leave inbox_instance_id out.
- target_inbox_inactiveHTTP 400
The target inbox is suspended.
Fix: Use another inbox, or leave inbox_instance_id out.
- schedule_rule_invalidHTTP 400
A repeating rule names a weekday twice (or is otherwise not a rule we can run).
Fix: List each weekday once, for example {"type":"weekly","days":["mon","thu"],"at":"09:00"}.
- invalid_time_zoneHTTP 400
time_zone is not an IANA time zone name we know.
Fix: Send a name like Europe/Istanbul, America/New_York or UTC.
- too_many_schedulesHTTP 409
This wake-up plan already holds 10 repeating rules.
Fix: DELETE /v1/utilities/{id}/schedules/{schedule_id} to remove one, or buy another wake-up-calls plan.
- schedule_not_foundHTTP 404
No repeating wake-up with this id on this plan.
Fix: GET /v1/utilities/{id}/schedules lists them.
- heartbeat_not_foundHTTP 404
No heartbeat check with this id on this plan, or (at /hb/{slug}) no live check at this ping address.
Fix: GET /v1/utilities/{id}/heartbeats lists the checks and their ping_url.
- too_many_heartbeatsHTTP 409
This heartbeat monitor already watches 10 jobs.
Fix: DELETE /v1/utilities/{id}/heartbeats/{heartbeat_id} to remove one, or buy another heartbeat-monitor.
- inbox_signature_invalidHTTP 401
At a pro inbox address: the sender's signature did not verify with the secret the agent set (reason says why: signature_missing, signature_mismatch, timestamp_too_old, secret_unreadable). Nothing was stored.
Fix: Senders: sign with the right secret. Agents: check the preset and secret with PATCH /v1/utilities/{id}/pro.
- invalid_challengeHTTP 400
A handshake challenge holds characters we do not echo (we echo up to 200 characters of A-Z a-z 0-9 . _ ~ -).
Fix: Nothing to do for the agent: real Slack, Zoom and Meta challenges fit.
- handshake_refusedHTTP 403
Meta's subscription check sent a hub.verify_token that is not the verify token set for this inbox.
Fix: Enter the same verify token in Meta's app settings as in handshakes.meta_verify_token.
- handshake_needs_secretHTTP 400
The Slack or Zoom handshake can only be answered for a request signed with that service's secret, and the matching verify preset is not set.
Fix: Send verify {"preset":"slack","secret":"<signing secret>"} (or "zoom" with the secret token) in the same call.
- forward_not_setHTTP 400
rotate_forward_secret was sent, but the plan forwards nowhere.
Fix: Set forward {"url":"https://..."} first; its key is in that answer.
- forward_url_unverifiedHTTP 400
The forwarding address did not prove it is yours: our check (a POST whose JSON has type agentmart.forward.verify and a challenge) did not get a 2xx answer with the hex sha256 of "agentmart-forward-verify:" followed by the challenge in its body (reason says why).
Fix: Make the address answer that POST with 200 and {"answer": "<that hex sha256>"}, then set forward again. At most 10 checks per plan per hour.
- inbox_pro_conflictHTTP 409
Another change to the same inbox's upgrade happened at the same moment; nothing was changed.
Fix: Send the same request again.
- inbox_pro_requiredHTTP 403
Bulk acknowledge and bulk delete come with webhook inbox pro, and no active pro plan of your owner upgrades this inbox.
Fix: Buy webhook-inbox-pro and PATCH /v1/utilities/{pro id}/pro {"inbox_instance_id": "<this inbox>"}.
- invalid_queue_nameHTTP 400
A queue name is 1 to 64 characters from a-z 0-9 . _ -, starting with a letter or digit.
Fix: Use a name like jobs, emails.outbound or crawl-2.
- queue_not_foundHTTP 404
No queue with this name on this plan.
Fix: Put a message to create it, or GET /v1/utilities/{id}/queues to list them.
- too_many_queuesHTTP 409
This durable queue plan already holds 10 queues.
Fix: DELETE /v1/utilities/{id}/queues/{name} to remove one, or put into an existing queue.
- queue_fullHTTP 409
The queue holds its max_messages already; nothing of this put was added.
Fix: Claim and ack, purge dead letters, or raise max_messages (up to 10,000) with PUT /v1/utilities/{id}/queues/{name}.
- queue_quota_exceededHTTP 413
The queues of this plan hold 20 MB of messages already; nothing of this put was added.
Fix: Ack or delete messages first.
- queue_message_too_largeHTTP 413
One message body is larger than 64 KB as JSON (index names which).
Fix: Put a smaller body, for example an id of the work instead of the work itself.
- verify_incompleteHTTP 400
The sender signature check misses something (missing names it): the first time it needs preset and secret, a new preset needs its own secret, hmac needs header; header, algorithm, encoding and prefix go only with hmac.
Fix: Send what is missing. Later changes need only the field that changes, for example {"verify": {"reject_unverified": true}}.
- forward_target_invalidHTTP 400
Forwarding into an inbox or a queue needs one of your own active webhook inboxes (not the one it copies from) or one of your own active durable queue plans with a valid queue name.
Fix: GET /v1/utilities lists your inboxes and queue plans; renew one that ended.
- schedule_parkedHTTP 409
The plan of this repeating wake-up ended, so the rule is parked and cannot run, not even as a test.
Fix: Renew the plan (POST /v1/orders with its instance_id); its rules run again from the renewal on.
- schedule_run_in_progressHTTP 409
A test run of this rule was started in the same second.
Fix: Wait a second, then POST .../run again.
- utility_expiredHTTP 410
The paid period of this utility is over. Writing answers 410; reading, exporting and deleting what it stores still work until our cleanup deletes it.
Fix: Renew with POST /v1/orders {"item": "<slug>", "instance_id": "<id>"}.
- no_settingsHTTP 400
PATCH /v1/utilities/{id} was sent for a utility that has no settings.
Fix: Only a form inbox has settings ({"digest": true|false} and {"site_name": "..."|null}).
- site_name_rejectedHTTP 400
A form inbox's site_name is shown to its visitors on our thank-you page, so it must be a plain name: this one has a link, a phone number, code, instructions, a request for a secret or another way to reach someone (reason and matched say which).
Fix: Use the plain name of the site, such as "Northwind Coffee".
- submission_not_foundHTTP 404
No entry with this id in this form inbox (deleted, or older than 30 days).
Fix: List entries with GET /v1/utilities/{id}/submissions.
- form_not_foundHTTP 404
No form inbox at this /f/ address.
Fix: Use the exact form_url from the order (GET /v1/utilities lists yours).
- form_closedHTTP 410
This form inbox expired and takes no entries.
Fix: Renew the form inbox with POST /v1/orders {"item": "form-inbox", "instance_id": "<id>"}; the address stays the same.
- form_fullHTTP 507
This form inbox holds 5,000 entries or 2 MB and refuses new ones until there is room. Stored entries are never pushed out.
Fix: Owner: export the entries, then DELETE /v1/utilities/{id}/submissions?through=<id>. Visitor: try again later.
- unsupported_form_typeHTTP 415
A form entry was sent with a Content-Type the form inbox does not take.
Fix: Send application/x-www-form-urlencoded (a plain HTML form), multipart/form-data without files, or application/json.
- files_not_supportedHTTP 415
A form entry carried a file. The form inbox takes text fields only.
Fix: Remove the file input from the form.
- invalid_formHTTP 400
The form entry could not be read: broken encoding, a field without a name, a name over 100 characters, or nested JSON.
Fix: Send flat named fields: text, numbers, true/false, or lists of those.
- empty_formHTTP 400
The form entry has no fields besides the control fields.
Fix: Give every input a name attribute.
- too_many_fieldsHTTP 400
The form entry has more than 50 fields.
Fix: Send at most 50 fields per entry.
- target_url_invalidHTTP 400
The URL is not an absolute https:// URL on port 443 without credentials, or it is longer than 2048 characters.
Fix: Send a public https:// URL.
- target_url_blockedHTTP 400
The URL points to a private, loopback, link-local, local or cloud metadata address, or its host name resolves to one (we look it up when you name the URL for an uptime check, a wake-up or repeating wake-up, or inbox forwarding, and again at every call). We only call public addresses.
Fix: Use the public https address of your app, or one of your inboxes as the target.
- too_many_checksHTTP 409
This uptime watch already watches its maximum of 3 URLs.
Fix: DELETE /v1/utilities/{id}/checks/{check_id} to stop one, or buy another uptime-watch.
- check_existsHTTP 409
This URL is already watched on this uptime watch. check_id names it.
Fix: Keep using that check.
- suppression_no_addressHTTP 400
None of the entries sent to an unsubscribe list (to add, or to make links for) is an email address. Nothing was added and no link was made. A call with at least one address answers as usual, each other entry marked not_an_address.
Fix: Send plain addresses, like ann@example.com.
- suppression_list_fullHTTP 409
An unsubscribe list holds at most 50,000 addresses, and the new ones you sent do not fit. Nothing was added. (Unsubscribes by people always go in.)
Fix: Remove addresses you no longer need, or buy another unsubscribe-list.
- suppression_key_unreadableHTTP 503
The list's own key cannot be opened on our side right now, so it cannot hash or check addresses. Nothing changed, and the list's data is kept. Our failure: we are alerted. (Also at /u and /mail-hooks: 503 with Retry-After.)
Fix: Retry later (Retry-After); we are alerted and fix this on our side.
- sendgrid_key_invalidHTTP 400
providers.sendgrid.public_key is not a SendGrid verification key (base64 of an ECDSA P-256 public key).
Fix: Copy the key from SendGrid: Settings, Mail Settings, Signed Event Webhook.
- mail_hook_not_foundHTTP 404
At /mail-hooks: no active list, or the provider is not set up for it.
Fix: Set the provider with PATCH /v1/utilities/{id} first; GET it for the webhook_url.
- mail_hook_signature_invalidHTTP 401
At /mail-hooks: the request did not prove it comes from the provider set up for this list (reason: signature_missing, signature_mismatch, timestamp_out_of_window, timestamp_too_old, topic_mismatch or certificate_unavailable). Nothing was read.
Fix: Agents: check the signing secret, key or topic in PATCH /v1/utilities/{id} providers. Senders: sign with the right secret.
- mail_hook_unreadableHTTP 400
At /mail-hooks/.../ses: the body is not an Amazon SNS message.
Fix: Turn raw message delivery OFF for the SNS subscription.
Emails to your owner
- heartbeat_name_rejectedHTTP 400
A check with email_owner puts its name into your owner's email, so the name must be plain words: this one has a link (also a dotted name after "click" or "visit"), a phone number (any, also one written out in words), a bank account or card number, code, instructions, a request for a secret or company framing, in any of our team's languages (reason and matched say which).
Fix: Use a short plain name such as "nightly backup", or leave email_owner off.
- reminder_text_rejectedHTTP 400
The reminder text breaks a rule (field, reason and matched say which): at most 500 characters of plain words, no links, email addresses, code, HTML or instructions, no requests for a secret, card numbers or bank details, no bank account or card number written out, no speaking as AgentMart or a company, no new bank details, no pressure to pay or decide now, no promise of a credit, refund or prize, no other channel; in English, Turkish, German, Spanish, French, Russian and Ukrainian.
Fix: Rewrite it as a plain reminder in your own words and send it again.
- too_many_remindersHTTP 409
This reminders plan already holds 5 reminders.
Fix: DELETE /v1/utilities/{id}/reminders/{reminder_id} to remove one.
- reminder_not_foundHTTP 404
No reminder with this id on this plan.
Fix: GET /v1/utilities/{id}/reminders lists them.
- reminders_stopped_by_ownerHTTP 409
Your owner pressed Stop reminders in a reminder email, so no reminder can be set or resumed for them.
Fix: Ask your owner in your own chat. Only they can turn reminders back on, with the link in any reminder email.
- email_not_configuredHTTP 503
Email is not switched on yet on our side. Nothing was sent.
Fix: Try again later; reach your human another way for now.
- email_limit_reachedHTTP 429
Your owner already got 50 AgentMart emails in the last 24 hours, from all products together. Nothing was sent.
Fix: Wait, then try again. Bundle messages where you can.
- owner_already_confirmedHTTP 409
POST /v1/me/owner-email/confirm: your owner already confirmed their address with AgentMart, so no confirmation email was sent.
Fix: Nothing to do: emails from your utilities reach your owner (GET /v1/me shows owner.email_confirmed: true).
- email_failedHTTP 502
The email provider did not confirm the email. It may still arrive.
Fix: Where the endpoint takes an idempotency key, retry with the same key: it never sends twice. Otherwise follow
next. - owner_unconfirmedHTTP 409
Your owner has not yet confirmed their address for AgentMart messages. They got a one-time confirmation email today at email_hint (masked, in the answer; at most one a day); nothing else was sent.
Fix: Ask your human to press Confirm in that email, then try again (GET /v1/me shows owner.email_confirmed). Only when your own pay link made the account and email_hint is not your human's address: POST /v1/me/leave and send your human a new pay link. An agent that joined with an invite code never leaves over this: it would lose the balance.
Project Blueprint
- unknown_stageHTTP 404
There is no stage with this name.
Fix: Use one of: concept, features, pages, database, tech_spec, tasks.
- stage_out_of_orderHTTP 409
Stages go in order, and an earlier stage is missing or stale (it no longer fits the stages before it).
Fix: PUT the stage named in
nextfirst. - stage_invalidHTTP 422
The stage did not pass our checks.
problemslists each one with itspath(and, for the database stage, the statement, line and PostgreSQL error). Nothing was saved.Fix: Fix every listed problem and PUT the stage again. Schema and example: GET /v1/blueprint/method?stage=<stage>.
- stage_conflictHTTP 409
The stage, or one before it, changed while yours was being checked (another agent of your owner saved at the same time). Nothing was saved.
Fix: Read the stages again (GET /v1/utilities/{id}/stages) and PUT yours again.
- stage_not_foundHTTP 404
This stage is not saved yet.
Fix: PUT it first. GET /v1/utilities/{id}/stages shows the next stage.
- sql_check_busyHTTP 503
The SQL check is busy with other schemas. Nothing was saved.
Fix: Wait
retry_after_sseconds and PUT the database stage again. - tasks_not_readyHTTP 409
This blueprint has no tasks yet.
Fix: Save the tasks stage first (send [] to let us build the list).
- task_not_foundHTTP 404
No task with this id in this blueprint.
Fix: GET /v1/utilities/{id}/tasks lists the task ids.
Human services
- job_not_foundHTTP 404
No job with this id for your owner.
Fix: GET /v1/jobs lists your owner's jobs.
- job_wrong_stateHTTP 409
The job is not in a state for this (
job_statussays which).Fix: GET /v1/jobs/{id} and follow
next. - question_not_foundHTTP 404
No open question with this id on this job.
Fix: GET /v1/jobs/{id}: question holds the open one.
- secret_already_setHTTP 409
This job already holds a secret, and an answer never replaces it. Nothing was saved.
Fix: Answer again without secret.
- answer_refusedHTTP 400
The answer or dispute reason holds something our team will not act on (
category), for example a password typed into the text, in any of our team's languages. Nothing was saved.Fix: Send the text again without it. While our team works with one console account no login is taken at all; otherwise a login goes only in
secret. - dispute_window_closedHTTP 409
Disputes are possible for 7 days after delivery.
Fix: Nothing to do: the job counts as accepted.
- nothing_left_to_creditHTTP 409
The whole price of this job was already credited back.
Fix: Nothing to do.
- dispute_item_unknownHTTP 400
An item id is not an item of this result (
disputable_itemslists them).Fix: Use ids from disputable_items, or leave item_ids out to dispute the whole result.
- dispute_existsHTTP 409
This item (or the whole result) is already disputed, or its dispute was answered.
Fix: GET /v1/jobs/{id} for the dispute's answer.
- job_not_cancellableHTTP 409
Only a job still waiting for its sites' proof (needs_verification) can be cancelled (
job_statussays where it is). From the queue on, its own rules credit it.Fix: GET /v1/jobs/{id} and follow
next. - evidence_not_foundHTTP 404
The evidence link is wrong, or older than 30 days after delivery (the file is deleted then).
Fix: GET /v1/jobs/{id} for fresh links while they work; the sha256 stays in the signed result.
- site_not_verifiedHTTP 409
Not every site of a website test is proved yet (
sitessays what each one still lacks). Our team does not start until they are.Fix: Publish the job's verification token for each site (a file, a DNS TXT record or a meta tag), then POST /v1/jobs/{id}/verify again.
- quote_input_requiredHTTP 400
A quote of a per-word or per-label service needs what we count: text (or item_count for labels), or the whole brief. A quote of the email check needs item_count: how many different entries the list has.
Fix: Send text, item_count or brief with the item.
- human_service_at_mcpHTTP 403
At /mcp/core, buy does not order human services: they are ordered and run at /mcp, where every tool of a job is. Nothing was reserved, held or charged.
Fix: Connect to /mcp, the same server and sign-in, and order it there with buy.
Email check
- check_not_foundHTTP 404
No email check with this id for your owner.
Fix: GET /v1/email-checks lists your owner's checks.
- consent_requiredHTTP 400
The list came without the consent statement: "consent": "own_opt_in_contacts" says These addresses are my owner's own contacts, who agreed to hear from my owner (opt-in). The list was not bought, rented, scraped, harvested or guessed, and it will not be used for spam. Nothing was taken.
Fix: Send it only when it is true. We never supply, find, guess or sell addresses.
- list_refusedHTTP 422
This does not look like your owner's own contact list (
reason: mostly_invalid_syntax, more than half of the different entries are not addresses; guessed_variants, several guessed forms of one person's address at one domain, named indomain; generated_domains, too many domains under one parent domain, named inparent_domain). Nothing was taken or stored.Fix: Send only your owner's own contacts, who agreed to hear from your owner.
- email_check_blockedHTTP 403
Your owner's account may not use the email check: we received complaints about its lists. Nothing was taken.
Fix: Your owner can write to us (/llms/wishes-and-contact.md) if this is a mistake.
- email_check_daily_capHTTP 429
Your owner already checked 10 lists in the last 24 hours, the most we check for one owner. Nothing was taken.
Fix: Wait retry_after_s seconds.
- email_check_busyHTTP 409
Your owner already has 2 lists being checked (or waiting for approval), the most at once. Nothing was taken. Retry-After is 60 seconds while a list is being checked; when every open list waits for your owner's approval, the answer says so, names their order ids in waiting_for_approval, and Retry-After is 900 seconds.
Fix: Send it when one of them has completed (after retry_after_s), or ask your owner to approve or decline the waiting orders.
- email_check_label_rejectedHTTP 400
The label is shown to your owner in emails, so it must be a plain name for the list (no links, phone numbers, code, instructions, requests for secrets or another way to reach someone). Nothing was taken.
Fix: Use a plain name, such as "Harbor Bikes newsletter", or leave label out.
Sender check
- sender_domain_invalidHTTP 400
domain is not a public domain name we can check: an email address, a web address, an IP address, a single word, or a local or reserved name (.local, .internal, .test, .example and similar). Nothing was taken.
Fix: Send just the domain your owner sends email from, like "example.com".
- sender_selector_invalidHTTP 400
An entry of dkim_selectors is not a DKIM selector (one or two DNS labels). Nothing was taken.
Fix: Send only the part before ._domainkey, like "s1" or "google".
- sender_check_daily_capHTTP 429
Your owner already checked 30 domains in the last 24 hours, the most we check for one owner. Nothing was taken.
Fix: Wait retry_after_s seconds.
- sender_check_domain_busyHTTP 429
Your owner already checked this domain 5 times in the last hour (your_checks_last_hour), or, rarely, the domain was checked the most times an hour we ask one domain's name servers (then only retry_after_s; other owners' checks are never shown). Nothing was taken. (Also an approval's failure_code, when the hour filled while the order waited for the owner.)
Fix: Wait retry_after_s seconds, or read your owner's recent check of it.
- sender_check_not_foundHTTP 404
No sender check with this id for your owner.
Fix: GET /v1/sender-checks lists your owner's checks.
Site check
- site_domain_invalidHTTP 400
Not a public domain name we can check (at most 6 parts).
Fix: Send just the domain of the website, like "example.com": no https://, no path, no email address and no IP address.
- site_mcp_url_invalidHTTP 400
mcp_url must be an https address on the same domain whose path names the MCP server (a segment mcp, or ending in sse).
Fix: Send the https address of the MCP server, like "https://example.com/mcp", or leave mcp_url out.
- site_check_cross_siteHTTP 403
A web page on another site sent this request from a browser. Call the API from your agent or server.
Fix: Send the request from your agent or your server, not from a script on a web page.
- site_check_opted_outHTTP 403
The domain's owner asked us not to check it.
Fix: Nothing to do: we do not check this domain for others. Nothing was read.
- site_check_target_busyHTTP 429
The server behind this domain was checked many times in the last hour. Retry after Retry-After.
Fix: Wait
retry_after_sseconds (also in the Retry-After header), then retry. Nothing was read. - site_check_not_foundHTTP 404
No such check, or it was deleted after 7 days.
Fix: Run a new check with POST /v1/site-checks.
- site_domain_not_provedHTTP 409
Publish the DNS record and prove the domain with POST /v1/site-domains first (in the last 7 days).
Fix: POST /v1/site-domains {"domain":"..."} shows the DNS record to publish. Publish it, send the same request again, then buy. Nothing was taken.
- site_domain_takenHTTP 409
Another owner runs a badge for this domain.
Fix: Nothing to do while that badge runs: a domain has one running badge at a time. Nothing was taken.
- site_badge_existsHTTP 409
Your owner already has a badge for this domain: renew it.
Fix: Renew it with POST /v1/orders {"item":"site-check-badge","instance_id":"..."}, the instance_id of this answer. Nothing was taken.
- site_badge_lapsedHTTP 409
This badge ended more than 30 days ago: buy a new one.
Fix: Buy a new badge with POST /v1/site-badges. Nothing was taken.
- site_badge_withdrawnHTTP 409
Our staff withdrew a badge for this domain: no badge can be bought or renewed for it until 30 days after that badge's plan ends.
Fix: If you think this is a mistake, write to mustafaakmese@ciphyr.ai. Nothing was taken.
- site_badge_endpointHTTP 400
Buy a first badge with POST /v1/site-badges.
Fix: Send POST /v1/site-badges {"domain":"..."}. To renew a badge, send its instance_id to POST /v1/orders. Nothing was taken.
- site_proof_lostHTTP 409
The domain's DNS record is gone; prove it again before renewing.
Fix: Put the DNS record back, send POST /v1/site-domains {"domain":"..."} to prove the domain again, then renew. Nothing was taken.
- site_badge_not_foundHTTP 404
No badge for this domain.
Fix: Check the domain name. A domain shows a badge only while its owner runs one.