// troubleshooting

Data source errors

Why a data source call was rejected and how to fix it. Argument validation details, unknown endpoints and sources, upstream failures, cost caps, and why an empty result is not an error.

Curated data sources are the data_<source>_* tools and the /v1/data/<source>/* REST routes. superagnt_ pays the upstream provider and charges your data credits per successful call. Arguments are checked against the source's schema before anything is sent upstream, and a call that fails for any reason costs nothing.

Rejected arguments: VALIDATION_ERROR

A call with a missing, malformed or wrongly typed argument is refused with VALIDATION_ERROR (HTTP 400) and one entry per bad field in details. Over REST the details are in error.details; over MCP they are in structuredContent.details.

validation detailsjson

{
  "code": "VALIDATION_ERROR",
  "message": "2 validation errors in request",
  "details": [
    { "field": "username", "location": "query", "message": "Required", "expected": "string" },
    { "field": "count", "location": "query", "message": "Expected number, received string", "expected": "number" }
  ]
}

field is the argument name, and location says where it goes: query, path or body.
message says what is wrong, and expected, when present, says what would be accepted.
Fix every listed field before calling again. Sending the same arguments gets the same answer.

The exact parameters, types and allowed values for every endpoint are in the API reference.

Grouped data tools

On the grouped surface a data tool takes an action plus that operation's arguments. If a required argument is missing you get MISSING_REQUIRED, which lists the missing arguments and includes the operation's input_schema. Arguments the operation does not declare are not passed to it, so check the spelling of optional arguments against input_schema when a filter seems to have no effect.

People and company lookups

The people and company tools (data_agnt_*, /v1/data/agnt/*) try more than one upstream provider. When every provider rejects the filters themselves, the answer is a 400 VALIDATION_ERROR whose message starts The data provider rejected these filters: and names the reason. Change the filter names or values to match the tool schema.

Wrong endpoint or source

Code	Status	What it means	What to do
`ENDPOINT_NOT_FOUND`	404	The source exists, but not that method and path on it.	Check the endpoint against the API reference for that source.
`PROVIDER_NOT_FOUND`	404	No source has that slug. The message lists the ones that do.	Use a slug from `GET https://api.superagnt.com/v1/platforms`.
`PROVIDER_NOT_FOUND`	503	The source exists but is not serving right now.	Retry later.
`PROVIDER_UNAVAILABLE`	503	The source is not set up correctly on our side.	Retry later. If it persists, open a ticket.

The upstream provider failed

Upstream failures are turned into one code rather than passed through raw:

What happened upstream	What you get	What to do
It answered 200 but the body was a failure	`PROVIDER_ERROR`, HTTP 422	Read the message. Usually the input points at something that does not exist upstream.
It answered with a 4xx	`PROVIDER_ERROR` with that same status, so a 404 from the source stays a 404	A 404 usually means the profile, post or page does not exist or is private. Do not retry unchanged.
It throttled the request	`PROVIDER_ERROR` with HTTP 429	Back off and retry.
It answered 5xx, timed out or could not be reached	`PROVIDER_ERROR`, HTTP 502	Retry with backoff.
Our account with it is out of quota	`UPSTREAM_CREDITS_EXHAUSTED`, HTTP 503	Retry later. See Credits and 402s.

None of these are billed.

Cost caps

Range and bulk endpoints take a cap, max_cost_cents or max_cost_cents_per_record. A cap below the endpoint's minimum is refused with VALIDATION_ERROR naming the minimum. On a builder plan, when the call's reserved budget is more than the included data credits left, the refusal is an upgrade offer with reason included_credits_insufficient; lowering the cap so it fits what is left lets the call run. See Plan limits and upgrade offers.

An empty result is not an error

A valid query that matches nothing succeeds with an empty page of results, or with email: null from the email finder. It is a successful call, and retrying will not change it. Widen or change the query instead.

When to open a ticket

Open a ticket with agnt_support_ticket_create when a call that matches the API reference is still rejected, when one source keeps returning 502 or 503 well after retries, or when results are clearly wrong rather than empty. Include the tool name or path, the arguments with anything personal redacted, the error code and message, and the time. See Getting help.