Skip to main content

​
Overview

Effective error handling ensures your integration with Alto Health is reliable and provides clear feedback when issues occur. This guide covers common errors, their causes, and how to resolve them.

​
HTTP Status Codes

Alto Health uses standard HTTP status codes to indicate the success or failure of API requests:
Request succeeded. The response body contains the requested data.When you’ll see this: Successful document uploads, extraction requests, and job status checks.
The request was malformed or missing required parameters.Common causes:
  • Missing required fields
  • Invalid data format
  • Invalid entity type
  • Malformed JSON
How to fix: Validate your request payload against the API documentation.
Authentication failed or API key is invalid.Common causes:
  • Missing API key header
  • Invalid API key
  • Expired API key
How to fix: Verify your API keys and ensure they’re included in request headers.
The request is valid but you don’t have permission to perform this action.Common causes:
  • API key has been revoked
  • Attempting to access another organization’s resources
  • Insufficient permissions
How to fix: Contact Alto Health support to verify your account status.
The requested resource doesn’t exist.Common causes:
  • Invalid job ID
  • Record has been deleted
  • Incorrect API endpoint URL
How to fix: Verify the resource ID and endpoint URL.
You’ve exceeded the rate limit.Rate limits:
  • Document Upload: 100 requests/minute
  • Entity Extraction: 50 requests/minute
  • Job Status: 300 requests/minute
How to fix: Implement exponential backoff and respect the retry_after header.
An unexpected error occurred on the server.Common causes:
  • Temporary server issue
  • Service degradation
  • Bug in API
How to fix: Retry the request with exponential backoff. If it persists, contact support.
The service is temporarily unavailable.Common causes:
  • Scheduled maintenance
  • System overload
  • Deployment in progress
How to fix: Wait and retry with exponential backoff.