ZoomInfo APIs use standard HTTP status codes to communicate the outcome of every request. Successful requests return a 200 status code, while client 4xx and server 5xx errors include structured error responses describing what went wrong and how to resolve it.

Failed requests return a structured error payload with additional details to help you troubleshoot, recover, and retry when appropriate.

Error Codes Reference

Client Errors (4xx)

400 – Bad Request

Error Code	Error Message	Recommended Action
PFAPI0001	Disallowed field '[field_name]' requested in query	Check user entitlements, remove disallowed fields, and verify field availability for the current API endpoint.
PFAPI0002	One or more fields have validation errors	Remove disallowed fields, validate input values, and contact your administrator for access if needed.
PFAPI0002	Required request parameters are missing: [parameter_name]	Verify all required parameters are included. Refer to the API documentation for a complete list.
PFAPI0002	Page number cannot be greater than max value 100	Ensure pagination does not exceed 100 pages.
PFAPI0003	Invalid request body	Validate JSON syntax and ensure the structure matches the API schema.
PFAPI0003	Invalid field requested	Remove or correct unrecognized fields. Refer to the official field documentation.
PFAPI0003	Invalid field type	Match field types with the expected schema. Use proper data types.
PFAPI0003	There is invalid field(s) in the request	Confirm that all fields match the schema definition.
PFAPI0004	There is not sufficient info for your request. Please provide at least one input field.	Add at least one valid input parameter.
PFAPI0004	Missing required inputs, please provide a value for at least one of [field1, field2, ...]	Include one or more of the required fields listed. Refer to endpoint documentation.
PFAPI0005	Invalid field requested	Ensure all field names are spelled correctly and are valid for the endpoint.
PFAPI0006	Input parameter '[parameter]' is invalid - [reason]	Use lookup endpoints for valid enumerated values and format strings correctly.
PFAPI0006	'[fieldMin]' cannot be greater than '[fieldMax]'	Ensure logical consistency between min and max values.
PFAPI0006	Invalid 'topics' (or some other values)	Check field constraints and validate values against allowed inputs.
PFAPI0008	Invalid field type	Ensure field types match the API specification. Convert inputs to appropriate types as needed.
PFAPI0009	Invalid field '[field]' requested in query	Refer to the field list for valid values. Remove or correct invalid fields.
PFAPI0009	OutputFields invalid or disallowed	Remove invalid entries from `outputFields`. Use lookup endpoints if needed to confirm valid fields.
PFAPI0011	Credit Limit Reached	User has reached their allocated Credit Limit, contact your ZoomInfo Administrator

401 – Unauthorized

Error Code	Error Message	Recommended Action
ZI0001	The token provided is invalid. Please provide a valid token and try again.	Verify the token format and contents. Regenerate if expired or malformed.
ZI0001	The Authorization token is required and cannot be left blank. Please provide a valid token and try again.	Include the `Authorization` header with a valid token in every request.
ZI0001	Your session has expired. Please provide a valid token and try again.	Re-authenticate and implement logic to refresh expired tokens automatically.

403 – Forbidden

Error Code	Error Message	Recommended Action
ZI0002	This application does not have the required scope to access the requested resource '[resource]'.	Request additional scopes from your ZoomInfo Administrator. Confirm required scopes per endpoint in the API documentation.
ZI0003	You do not have access to this endpoint. Please contact your ZoomInfo Account Manager for purchasing options.	Review your account's access level. Contact your Account Manager to enable access or upgrade your subscription.
ZI0003	You do not have permission to access the ZoomInfo API.	Confirm your subscription includes API access. Contact ZoomInfo support or your Account Manager to enable access.

429 – Too Many Requests

Error Code	Error Message	Recommended Action
ZI0004	You have exceeded the rate limit for this resource. Please try again later.	Implement exponential backoff. Review rate limits in the documentation. Consider request batching to reduce frequency.

Server Errors (5xx)

500 – Internal Server Error

Error Code	Error Message	Recommended Action
PFAPI0007	Internal Server Error	Retry after a short delay. If the issue persists, check system status or contact ZoomInfo support.

504 – Gateway Timeout

Error Code	Error Message	Recommended Action
PFAPI0010	Gateway Timeout Exception	Retry the request after a delay. If timeouts are frequent, reduce request size or complexity, and contact support if needed.

Error Response Format

{
  "error": {
    "code": "ZI0004",
    "message": "You have exceeded the rate limit for this resource. Please try again later.",
    "status": 429,
    "requestId": "req_abc123",
    "retryable": true
  }
}

Best Practices for Error Handling

Implement proper retry logic for 5xx errors with exponential backoff
Cache authentication tokens and refresh them before expiration
Validate input parameters before making API calls to avoid 4xx errors
Monitor rate limits and implement request throttling for 429 errors
Log error details for debugging while avoiding sensitive information exposure
Provide meaningful error messages to end users based on error codes

Agent Recovery Guidance

AI agents should recover differently based on error type.

Missing required parameter	Ask the user for the missing input or infer it only if obvious
Invalid lookup value	Call Lookup and retry with the returned ID
Page number above max	Reduce page number or restart pagination
Expired token	Refresh token or ask user to reconnect
Missing scope	Explain required scope and stop
Entitlement error	Explain that the user's package does not include the requested field or endpoint
Rate limit	Back off and retry
Gateway timeout	Reduce request size or complexity

Example Agent Error

The search failed because "SaaS" is not a valid industry value in the API request. I am going to resolve the correct industry ID with Lookup and retry the search.

For additional support and documentation, use the "Need Help" button at the bottom right of the page.