---
updatedAt: 2026-07-24T12:56:48.000Z
agentTools:
projectIndex: https://docs.gtm.ai/llms.txt
---
# Status Codes and Errors
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
```json
{
"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**
```text
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.*
# Sibling pages
* [API Conventions](https://docs.gtm.ai/zoominfoenterprise/docs/api-conventions.md)
* [Rate Limits](https://docs.gtm.ai/zoominfoenterprise/docs/rate-limits.md)
* [Pagination, Batching and Bulk](https://docs.gtm.ai/zoominfoenterprise/docs/pagination-batching-and-bulk.md)
* [Webhook and Events](https://docs.gtm.ai/zoominfoenterprise/docs/webhook-and-events.md)
* [ZoomInfo OAuth Scopes](https://docs.gtm.ai/zoominfoenterprise/docs/zoominfo-oauth-scopes.md)
* [OpenAPI Specifications](https://docs.gtm.ai/zoominfoenterprise/docs/openapi-specifications.md)
* [Credit Usage and Limits](https://docs.gtm.ai/zoominfoenterprise/docs/credit-usage-and-limits.md)