Error Codes
When a tool encounters an error, it returns a structured error object that AI agents can parse and act on.
Error response format
{
"success": false,
"error": {
"message": "Human-readable explanation of what went wrong",
"code": "ERROR_CODE",
"category": "validation",
"severity": "low"
}
}Error codes
| Code | Category | Severity | Description |
|---|---|---|---|
INSUFFICIENT_CREDITS | api_client_error | high | Account has no remaining credits. Upgrade your plan or wait for renewal. |
INVALID_DATAPOINTS | validation | low | Not enough identifying data provided. Add more fields (LinkedIn URL, email, or name + company). |
NO_MATCH | api_client_error | low | Enrichment could not match a record. For enrich_person, also returned when only_verified_email / only_verified_mobile is set but no verified contact was found. |
NO_RESULTS | api_client_error | low | Search returned no results for the given filters. |
INVALID_REQUEST | validation | low | Malformed request. Check required fields and formatting. |
INVALID_FILTERS | validation | low | One or more search filters are invalid. Check filter names and values. The response may include a filter_error detail. |
RATE_LIMITED | rate_limit | medium | Too many requests. Wait before retrying. |
INTERNAL_ERROR | api_server_error | high | Prospeo encountered an internal error. Retry the request. |
INVALID_API_KEY | configuration | critical | API key is invalid. Check your PROSPEO_API_KEY environment variable. |
ACCOUNT_RESTRICTED | api_client_error | critical | Account is restricted. Contact support@prospeo.io. |
NETWORK_ERROR | api_server_error | high | Could not reach the Prospeo API. Check network connectivity. |
TIMEOUT | api_server_error | medium | Request timed out. Try again or increase PROSPEO_TIMEOUT. |
VALIDATION_ERROR | validation | low | Tool arguments failed schema validation. Check the parameter types and values. |
Categories
| Category | Meaning |
|---|---|
validation | Input data is wrong — fix the request and retry. |
configuration | Setup issue (bad API key, missing env var). |
api_client_error | Account-level issue (no credits, restricted). |
api_server_error | Prospeo API or network issue — retry may help. |
rate_limit | Too many requests — back off and retry. |
Severity levels
| Severity | Meaning |
|---|---|
low | User can fix by adjusting input. |
medium | Transient issue, retry likely works. |
high | Requires attention (credits, network). |
critical | Blocks all operations (bad key, restricted account). |
Last updated on