Error Reference

All API errors return a JSON body with an error message and a code identifier.


{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": "Optional additional context"
}

Error Codes

HTTP Status	Code	Description	What To Do
400	`VALIDATION_ERROR`	Missing or invalid request fields	Check your request body matches the schema. `prompt` is required and must be 1–10,000 chars.
400	`TX_NOT_FOUND`	Transaction hash not found on Base	Verify the tx hash is correct and the transaction is confirmed. Wait a few seconds if just submitted.
400	`TX_FAILED`	Transaction failed on-chain	The USDC transfer did not succeed. Check your wallet balance and try again.
400	`INVALID_PAYMENT`	No USDC transfer to gateway wallet found in tx	The transaction doesn’t contain a USDC transfer to the correct wallet. Check the recipient address.
400	`INSUFFICIENT_PAYMENT`	Transfer amount is less than endpoint price	You need to send at least the endpoint price in USDC. Check pricing in the agent manifest.
400	`TX_ALREADY_USED`	This transaction hash was already submitted	Each tx can only be used once. Make a new USDC transfer for each generation.
402	—	X402 payment challenge	Normal X402 flow. Sign the payment and retry with `X-PAYMENT` header. Handled automatically by `x402-fetch`.
404	`NOT_FOUND`	Endpoint or task not found	Check the slug or task ID. The endpoint may have been removed or the task ID is invalid.
429	—	Rate limited	Too many requests. Wait and retry. Check the `Retry-After` header for how long to wait.

HTTP Status	Code	Description	What To Do
500	`INTERNAL_ERROR`	Internal server error	Unexpected failure. Try again. If persistent, the service may be down.
500	`EXECUTION_ERROR`	Generation failed	The AI provider returned an error. Try a different prompt or try again later.

These appear in the task status response when status: "failed":

Code	Description	What To Do
`GENERATION_FAILED`	AI provider failed after all retries	Try a different prompt. Some prompts may be rejected by the provider’s safety filters.

Rate limits are per IP address. When rate limited, you’ll receive HTTP 429 with a Retry-After header indicating when you can retry.

Always validate your request before sending — check prompt length, tx hash format, and slug existence
Handle 402 gracefully — it’s not an error, it’s the normal X402 payment negotiation
Poll responsibly — use 2-second intervals for task status, not faster
Budget for retries — the server retries failed generations 3 times automatically; wait for the final status before retrying yourself