Errors
PowaAgent reports errors in two places:
- The connector (MCP) returns tool errors with a category and a message.
- The PowaAgent API returns HTTP errors in the
application/problem+jsonformat.
When a payment is refused, nothing is signed and nothing is spent.
Payment refusals (403)
These come from your source policy or your signing access:
type (after https://problems.certaindata.com/) | title | Example detail | What to do |
|---|---|---|---|
deny-listed | Seller deny-listed | Seller deny-listed: api.example.com/v1/data | Remove the entry from your deny list if you want to allow this seller |
allow-pending | Seller approval pending | Seller pending user approval: api.example.com/v1/weather | Approve the seller under Pending approvals, then try again |
ecosystem-source-not-permitted | Ecosystem source not permitted | Open ecosystem source not permitted: … or Buyer-approved source not permitted: … | Turn on Open Ecosystem or Buyer Approved endpoints on Source policy |
spend-cap-exceeded | Spend cap exceeded | Per-call cap exceeded: 15000 > 10000 | Raise the cap, or wait for the 24-hour or 30-day window to move on |
grant-revoked | Grant revoked | Renew access on the Dashboard | |
grant-expired | Grant expired | Renew access on the Dashboard | |
grant-not-found, grant-not-authorized, grant-not-enabled | Grant not found / not authorized / not enabled | Renew access on the Dashboard. If it persists, contact support. |
Amounts in cap messages are in USDC base units, where 1,000,000 = 1 USDC. So 15000 > 10000 means a $0.015 payment against a $0.01 cap.
Other API errors
| Status | Body | Meaning |
|---|---|---|
400 | {"title": "Bad request", "status": 400, "invalidParams": [{"name", "reason"}]} | The request body is malformed or missing a required field |
401 | {"message": "Unauthorized"} | The API key is missing, invalid, expired or revoked. See Authentication. |
404 | {"title": "Not found", "status": 404, "detail": "User not found: …"} | Your account couldn't be found, for example because the wallet setup wasn't finished |
409 | Test funds requested before your wallet was set up | |
422 | {"title": "Unprocessable entity", "status": 422, "detail": "…"} | The payment terms can't be signed, for example an unsupported network or missing extra.name/extra.version |
429 | Test funds were requested within 24 hours of the last request | |
500 | {"title": "Internal server error", "status": 500} | Something went wrong on our side. Try again. |
502 | {"title": "CDP signing failed", "status": 502, "detail": "…"} | Coinbase didn't complete the signature in time (20 seconds) or returned an error. Try again. |
Connector (MCP) errors
When a tool call fails, the connector returns an MCP tool error (isError: true) with a readable message and structured content. In this example the seller URL is illustrative:
{
"category": "forbidden_policy",
"message": "Seller approval pending: Seller pending user approval: api.example.com/v1/lookup",
"detail": {
"status": 403,
"type": "https://problems.certaindata.com/allow-pending",
"title": "Seller approval pending",
"problem_detail": "Seller pending user approval: api.example.com/v1/lookup"
}
}
category | Meaning |
|---|---|
bearer_required | A paying tool was called without a credential |
unauthorized | The credential was rejected |
forbidden_policy | Your source policy or signing access refused the payment. detail.type gives the reason (see the 403 table above). |
not_found | Your account or wallet couldn't be found |
unprocessable | The request or the seller's payment terms couldn't be used |
rate_limited | Too many requests. For test funds, try again after 24 hours. |
no_acceptable_payment | The seller doesn't offer USDC on Base |
sandbox_unavailable | You asked for the sandbox, but the service doesn't have one |
wallet_not_provisioned | Your wallet hasn't been set up yet |
invalid_input / missing_input | A tool argument is wrong or missing. detail.field names a missing one. |
seller_error | The seller returned an error, including after payment |
payment_unconfirmed | The connection failed after the payment was sent. It may have settled, so check your Transactions before paying again. |
signature_not_yet_valid | The signature isn't valid yet. Try again shortly. |
upstream_error | A PowaAgent dependency failed. Try again. |
egress_blocked | The URL isn't allowed to be called, for example a private address |
unknown_tool | The tool isn't in the current catalog. Ask your client to refresh its tool list. |
Seller errors
When a seller returns an error after a payment is signed:
- Through the connector, you get a
seller_errorwith the seller's HTTP status code indetail.status_code. The seller's own error body isn't passed on. If the seller rejected the payment itself, the message gives its reason when it sent one. - When you call the seller yourself, for example with the Skill or the API, you get the seller's response unchanged.
Whether a seller charges for a call that returns an error is up to the seller.