Error Codes
All API errors return a consistent JSON structure with an HTTP status code, error type, and human-readable detail message.
Error Response Format
json
{
"error": {
"code": 422,
"type": "validation_error",
"message": "Invalid state code 'XX'. Use a two-letter US state abbreviation.",
"request_id": "req_abc123xyz"
}
}Always include the request_id when contacting support about an error.
HTTP Status Codes
| Code | Name | Description | Resolution |
|---|---|---|---|
| 400 | Bad Request | Missing or invalid parameters. Check the error detail for specifics. | Validate request body against the schema for the endpoint. |
| 401 | Unauthorized | API key is missing or invalid. | Include a valid X-API-Key header. Check the key is active in your dashboard. |
| 403 | Forbidden | API key lacks permission for this endpoint, or request IP is not whitelisted. | Use a key with the correct type (Standard or Full Access). Check IP whitelist settings. |
| 404 | Not Found | The requested resource does not exist. | Verify the resource ID. For contacts, ensure the ID was returned from a search. |
| 409 | Conflict | Duplicate resource. The webhook URL or auto-buy rule already exists. | Update the existing resource instead of creating a duplicate. |
| 422 | Unprocessable Entity | Request is well-formed but semantically invalid. | Check field values. Common causes: invalid state codes, unsupported industry names. |
| 429 | Too Many Requests | Rate limit exceeded for your tier. | Back off and retry after the time indicated in Retry-After header. See Rate Limits. |
| 451 | Unavailable For Legal Reasons | FCRA-regulated field requested. SIE Data does not distribute FCRA data. | Remove the blocked field from your request. See compliance documentation. |
| 500 | Internal Server Error | An unexpected error occurred on our side. | Retry with exponential backoff. If persistent, contact support. |
| 502 | Bad Gateway | An upstream enrichment source is temporarily unavailable. | Retry after a few seconds. The enrichment pipeline will route around failing sources. |
| 503 | Service Unavailable | The API is undergoing maintenance or is overloaded. | Check status.siedata.dev for outage information. Retry with backoff. |
Error Handling Best Practices
- Always check the HTTP status code before parsing the response body.
- Implement exponential backoff for 429 and 5xx errors.
- Log the
request_idfor debugging and support requests. - Never retry 4xx errors (except 429) without fixing the request first.
- Use the
Retry-Afterheader value when present.