Errors

Errors return a JSON body with a human-readable error and a stable machine-readable code.

{
  "error": "Invalid wallet address format. Expected 0x followed by 40 hex characters.",
  "code": "INVALID_ADDRESS"
}

Branch on code. The error string is written for humans and may be reworded.

Codes

Code	Status	Cause
`MISSING_API_KEY`	401	No `Authorization` header.
`INVALID_API_KEY`	401	Key is unrecognized, revoked, or expired.
`RATE_LIMIT_EXCEEDED`	429	A per-minute, per-day or per-month limit was hit. See rate limits.
`INVALID_ADDRESS`	400	An address is not `0x` plus 40 hex characters.
`INVALID_HANDLE`	400	X handle is not 1 to 15 characters of letters, numbers or underscores.
`INVALID_USERNAME`	400	Farcaster username is not 1 to 32 characters of letters, numbers, dots or hyphens, starting with a letter or a number.
`INVALID_PARAMETER`	400	A query parameter is out of range, such as an unrecognized `period`.
`INVALID_CURSOR`	400	A `cursor` value the API did not produce, on the reverse-lookup endpoints.
`INVALID_REQUEST`	400	Body is missing, not valid JSON, `wallets` is absent or empty, an `Idempotency-Key` header is over 200 characters, or a job id is not a UUID.
`INVALID_REQUEST`	413	Request body exceeded the endpoint’s cap: 1 MB on batch and estimate, 4.5 MB on jobs.
`BATCH_SIZE_EXCEEDED`	400	More wallets than your plan’s batch ceiling, on batch or estimate. 50 on the default plan; a live Scale or Index pack raises it (see plans). The message names your ceiling.
`LIST_TOO_SMALL`	400	An estimate with fewer than 10 distinct wallets. The counts are aggregates by design; for one address, resolve it.
`SUBMISSION_LIMIT_EXCEEDED`	402	A job list longer than 10 times your match balance. The message names the maximum; shorten the list or top up.
`JOB_ALREADY_ACTIVE`	409	The account already has a pending or processing job, on any surface. The message names its id; poll it and resubmit when it completes.
`JOB_NOT_FOUND`	404	No job with this id is visible to this account. A job another account submitted answers exactly this.
`NO_CREDITS`	402	Match credit balance is exhausted, or the free 30-day allowance is used up. Buy a pack, on either rail below. Only the metered endpoints return it; `/v1/stats`, `/v1/usage`, `/v1/estimate` and the job status poll answer at any balance.
`IDEMPOTENCY_KEY_REUSED`	422	The same `Idempotency-Key` was sent with a different request body inside the 24-hour window. Use a fresh key for a new request. Batch only.
`IDEMPOTENCY_NOT_REPLAYABLE`	409	The original response under this `Idempotency-Key` was too large to store, so it cannot be replayed. Resend under a fresh key; the resend bills as a new request. Batch only.
`SERVICE_UNAVAILABLE`	503	Datastore is temporarily unreachable. Retry with backoff.
`INTERNAL_ERROR`	500	Unexpected failure on our side.

Running out of credits

Every metered endpoint checks your match balance before it runs. The free endpoints, /v1/stats, /v1/usage, /v1/estimate and the job status poll, skip the refusal and answer at any balance, so a drained key can always read its own meter, estimate its next list, and collect the results of a job it already paid for; that reading is the signal to top up. On a metered endpoint with nothing left, the call returns 402 with one of two error strings, depending on whether you are spending the free allowance or a pack:

{
  "error": "Free allowance used up for this 30-day window. Buy a pack at https://walletlink.social/pricing to continue, or buy one with USDC, no account needed, at POST https://walletlink.social/api/x402/buy.",
  "code": "NO_CREDITS"
}

{
  "error": "No credits left. Buy a pack at https://walletlink.social/pricing to continue, or buy one with USDC, no account needed, at POST https://walletlink.social/api/x402/buy.",
  "code": "NO_CREDITS"
}

The free allowance is 100 matches per rolling 30 days. A pack adds a balance that lasts 12 months, and the API draws on it exactly as the app does. Both strings carry both remedies. A person buys a pack at walletlink.social/pricing; an agent holding a wallet buys credits with USDC over x402, no account, at POST https://walletlink.social/api/x402/buy. See the agent pack.

Things that are not errors

Two cases return HTTP 200 and are easy to mistake for failures. A wallet with no identities. data: null, meta.found: false. The lookup succeeded and the answer is that there is nothing attached. See found, missing, and checked. A reverse lookup with no matches. data: [], meta.total_count: 0.

Retrying

SERVICE_UNAVAILABLE and INTERNAL_ERROR are worth retrying with exponential backoff. RATE_LIMIT_EXCEEDED is worth retrying once the window resets. A retried request bills again, because a retry is a second resolution. The exception is a batch resent with the same Idempotency-Key: inside the 24-hour window it replays the stored response, marked Idempotency-Replayed: true, and bills nothing. Send the header on any batch you might have to retry. A job resubmission is refused with JOB_ALREADY_ACTIVE while the original runs, so a job cannot double-run by accident; resubmitted after completion, it runs the whole list again and bills again. Poll before resubmitting. NO_CREDITS is not worth retrying. It clears when you buy a pack, or when the free window rolls forward. Nothing in the 400 family is worth retrying. The request is malformed and will fail identically until you change it. BATCH_SIZE_EXCEEDED is the exception in spirit: split the batch and retry the pieces. 401 means the key is wrong. Retrying will not fix it and repeated failures are a good way to look like an attack.

Overview

Lookups

Jobs

Reverse lookups

Account

Codes

Running out of credits

Things that are not errors

Retrying

​Codes

​Running out of credits

​Things that are not errors

​Retrying

Codes

Running out of credits

Things that are not errors

Retrying