Error Handling

The Prooflio API uses conventional HTTP status codes and returns a consistent JSON error body so you can handle failures programmatically.

Error Response Format

Every error response includes three fields:


{
  "error": "unauthorized",
  "message": "Invalid or missing API key.",
  "details": []
}

Field	Type	Description
`error`	`string`	A machine-readable error code (e.g., `unauthorized`, `rate_limit_exceeded`).
`message`	`string`	A human-readable summary of the error.
`details`	`array`	An array of objects providing additional detail. May be empty.

Success Codes

Status Code	Meaning	When Returned
`200 OK`	Request succeeded.	All successful `GET` requests.

Client Error Codes

Status Code	Error Code	Meaning
`400 Bad Request`	`bad_request`	The request is malformed or contains invalid query parameters.
`401 Unauthorized`	`unauthorized`	API key is missing, invalid, expired, or revoked.
`403 Forbidden`	`forbidden`	API key is valid but the plan does not include API access.
`404 Not Found`	`not_found`	The requested resource does not exist (e.g., invalid widget ID).
`429 Too Many Requests`	`rate_limit_exceeded`	You have exceeded the rate limit. See Rate Limits.

Server Error Codes

Status Code	Error Code	Meaning
`500 Internal Server Error`	`internal_error`	An unexpected error occurred on our side. Try again later.

If you receive a 500 error repeatedly, please contact support with the request details so we can investigate.

Error Handling Example


const response = await fetch('https://app.prooflio.io/api/v1/reviews', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
});
 
if (!response.ok) {
  const error = await response.json();
 
  switch (response.status) {
    case 401:
      console.error('Authentication failed. Check your API key.');
      break;
 
    case 403:
      console.error('API access requires a Growth plan or higher.');
      break;
 
    case 429:
      const retryAfter = response.headers.get('Retry-After');
      console.error(`Rate limited. Retry after ${retryAfter} seconds.`);
      break;
 
    default:
      console.error(`Error (${response.status}): ${error.message}`);
  }
} else {
  const { data, pagination } = await response.json();
  console.log(`Fetched ${data.length} of ${pagination.total} reviews`);
}