Error Handling
🚀 ZoomInfo API Documentation
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. |
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. |
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
For additional support and documentation, contact your ZoomInfo API representative.
Updated 27 days ago