All error responses use a consistent JSON envelope. Check the code field for machine-readable identification — the message field is human-readable and may change between releases.
Error envelope
{
"error": {
"code": "provider_not_found",
"message": "No provider was found for the supplied NPI."
}
}
Field
Type
Description
error.code
string
Machine-readable snake_case identifier. Use this in your error handling logic.
error.message
string
Human-readable description. Do not rely on exact wording in production code.
HTTP status codes
Status
Meaning
200
Success. The request was accepted and processed.
400
Bad request. A parameter was missing, malformed, or otherwise invalid.
401
Unauthorized. The API key was missing or invalid.
404
Not found. The requested resource does not exist in the dataset.
422
Unprocessable. The request was well-formed but semantically invalid (e.g. NPI fails check-digit).
429
Too many requests. Monthly quota or burst limit exceeded.
500
Server error. Unexpected internal failure — try again later.
Error code reference
Authentication
Code
HTTP
Description
missing_api_key
401
No Authorization header was present on the request.
invalid_api_key
401
The key was present but is not recognized or has been revoked.
Rate limiting
Code
HTTP
Description
burst_rate_limit_exceeded
429
Too many requests in the current rolling window. Check Retry-After header.
monthly_quota_exceeded
429
Monthly request quota exhausted. Response includes limit, used, and reset_at fields.
NPI validation
Code
HTTP
Description
invalid_npi_format
400
The supplied NPI is not exactly 10 digits.
invalid_npi_checksum
422
The NPI is 10 digits but fails the standard NPI check-digit algorithm. This cannot be a real, assigned NPI.
provider_not_found
404
The NPI passed validation but no matching provider was found in the NPPES dataset.
Geographic search
Code
HTTP
Description
invalid_location
400
Location parameters are missing or invalid. Provide either zip or both lat and lng.