Skip to content
metzia
Sign in
Documentation

Reference

Errors

On this page

When a Metzia tool rejects a call, the response gives an error code and tells you whether retrying can help. This page explains every code. The docs_url field links directly to the relevant section. The scope_missing error uses a different response format; see the last section of this page.

The connection guide shows both error formats, with an example of each.

The shape of an errorLink to this section

A tool error carries a stable code, a message a person reads, and retryable. It carries field when one argument is at fault, and retry_after_seconds on rate_limited.

{
  "code": "invalid_input",
  "message": "We can't answer with these arguments. Fix the named field and call again.",
  "retryable": false,
  "field": "query",
  "docs_url": "https://metzia.ai/docs/errors#invalid_input"
}

The codesLink to this section

invalid_inputLink to this section

The tool cannot answer with these arguments. The field value identifies the argument to fix. Change it, then call the tool again. Retrying without changes will fail again.

not_foundLink to this section

No published product matches that ID. The message names the ID and gives no reason, so it doesn't reveal what state a listing is in. Call search to find an available product. Retrying with the same ID will fail again.

The message identifies the product by its ID alone. It never quotes text a seller wrote.

handoff_unavailableLink to this section

The listing is live, but Metzia cannot create a purchase link. The message includes the listing URL without affiliate tracking. Send the buyer to that URL. Retrying the same call will fail again.

unauthenticatedLink to this section

Metzia couldn't verify the credentials sent with this call. Reconnect the client, then call the tool again.

forbiddenLink to this section

Your credentials are valid, but they don't allow this action. Don't retry. The refusal field explains the specific reason. email_unverified means the buyer hasn't verified their email address. terms_not_accepted means the buyer hasn't accepted the Terms of Service.

rate_limitedLink to this section

Your connection has reached its request limit. Wait for the number of seconds given in retry_after_seconds, then call the tool again.

refusal names a daily limit when one applies. retrieval_limit says the connection, or the account across all of its connections, received more distinct products today than Metzia serves. pagination_limit says it read more search pages through a cursor today than Metzia serves. Both waits run to the next midnight UTC. After pagination_limit, a search without a cursor still answers.

upstream_unavailableLink to this section

A service Metzia needs didn't respond. We've recorded the error. Try again shortly. If the error includes retry_after_seconds, wait that many seconds first.

timeoutLink to this section

The tool took too long to answer. Call again.

internalLink to this section

An error on our side prevented the tool from completing your request. We've recorded it. Try again. If you contact support, include the request ID.

scope_missingLink to this section

The token lacks the scope the tool needs. The result carries no envelope. It carries _meta.error_code and _meta.required_scope, which names the scope. Connect again and grant that scope. Do not call again with the same token.

Updated 2026-10-03