Overview The Explorium API uses standard HTTP response codes to indicate the success or failure of requests. Responses include detailed error information to help you identify and resolve issues quickly.
All error responses follow a consistent structure:
HTTP/ 1.1 400 Bad Request Content-Type: application/json { "details" : "Human-readable error description" , "correlation_id" : "unique-id-for-troubleshooting" , } Important The correlation_id is crucial for troubleshooting. Always include it when contacting support.
HTTP Status Codes Status Code Type Description :--- :--- :--- 200 Success Request completed successfully 201 Success Resource created successfully 400 Client Error Bad request - Invalid request format or parameters 401 Client Error Unauthorized - Authentication failed 403 Client Error Forbidden - Valid request but insufficient permissions 422 Client Error Unprocessable Entity - Request validation failed 429 Client Error Too Many Requests - Rate limit exceeded 500 Server Error Internal Server Error - Unexpected server issue 503 Server Error Service Unavailable - Temporary server issue
Error Types Authentication Errors (401) Error Message Description Resolution Partner ID is missing. Please set it in one of these headers: X-Context-Partner-ID, partner-id, partner_id.Request missing required Partner ID header Add Partner ID to request headers Partner ID is invalid. Please set the Partner ID in one of these headers: X-Context-Partner-ID, partner-id, partner_id.Provided Partner ID is not recognized Verify your Partner ID is correct
Credit Errors (403) Error Message Description Resolution You have insufficient credits to perform this operation. Please purchase additional credits.Credit balance too low for requested operation Purchase additional credits or contact your account manager
Validation Errors (422) Validation errors return a detailed structure indicating which fields failed validation:
HTTP/ 1.1 422 Unprocessable Entity Content-Type: application/json { "detail" : [ { "loc" : [ "body" , "field_name" ], "msg" : "validation error message" , "type" : "error_type" , "ctx" : { "additional" : "context" } } ] } Common Validation Errors: Field Error Type Message Resolution sizevalue_error.number.not_leensure this value is less than or equal to 100Reduce the size parameter to ≤ 100 pagevalue_error.number.not_geensure this value is greater than or equal to 1Page numbers start at 1 filtersvalue_error.missingfield requiredInclude the required filters object
Client Errors (400) Error Message Description Resolution Client webhook failed on: [details]Your webhook endpoint failed to process the event Check webhook endpoint availability and response
Server Errors (500) Error Message Description Resolution An internal server error occurredUnexpected server error Retry with exponential backoff; contact support if persists
Rate Limiting When you exceed API rate limits, you’ll receive a 429 response:
{ "code" : 429 , "message" : "Rate limit exceeded. Please retry after the specified time." , "retry_after" : 60 // Seconds to wait before retrying } Rate Limit Headers:
X-RateLimit-Limit: Maximum requests per windowX-RateLimit-Remaining: Requests remaining in current windowX-RateLimit-Reset: Unix timestamp when limit resets
Best Practices
Log correlation IDs for all errors to facilitate debuggingImplement retry logic with exponential backoff for 5xx errorsMonitor credit usage to avoid unexpected 403 errorsValidate requests client-side to minimize 422 errorsHandle rate limits gracefully using the retry_after value
Don’t retry 4xx errors without fixing the root cause
Don’t ignore correlation IDs when reporting issues
Don’t make parallel requests that might exceed rate limits
Don’t cache error responses
Error Handling Examples import requests from time import sleep def make_api_request ( url , headers , data ): response = requests.post(url, headers = headers, json = data) if response.status_code == 429 : retry_after = int (response.headers.get( 'Retry-After' , 60 )) sleep(retry_after) return make_api_request(url, headers, data) if response.status_code >= 500 : # Implement exponential backoff for attempt in range ( 3 ): sleep( 2 ** attempt) response = requests.post(url, headers = headers, json = data) if response.status_code < 500 : break if response.status_code >= 400 : error_data = response.json() print ( f "Error: { error_data[ 'message' ] } " ) print ( f "Correlation ID: { error_data[ 'correlation_id' ] } " ) return response
Troubleshooting When Contacting Support Please provide the following information:
Correlation ID from the error responseRequest details :
Endpoint URL
HTTP method
Request headers (excluding sensitive data)
Request body
Timestamp of the errorError message and status code Quick Troubleshooting Tips
401 Errors : Double-check your Partner ID and API key403 Errors : Verify your credit balance in the dashboard422 Errors : Review the validation error details and adjust your request429 Errors : Implement rate limiting in your application500 Errors : These are usually temporary - retry with exponential backoff
Change Log Version Date Changes v1.5 June 2025 Enhanced error handling with specific error codes and improved messages v1.4 - Added 10K enrichments v1.3 - Added prospects match v1.2 - Added Social media posts and workforce trends v1.1 - Added events pipelines v1.0 - Initial release
Need Help? Contact our support team through your dedicated Slack channel with Explorium.
