Skip to main content

​
Error Format

All error responses follow the same format: 
{
  "error": "Human-readable error message"
}

​
HTTP Status Codes

CodeDescriptionCommon causes
400Bad RequestMissing required fields, invalid parameters
401UnauthorizedMissing or invalid API key
403ForbiddenInsufficient permissions for the operation
404Not FoundResource doesn’t exist or doesn’t belong to your company
500Internal ErrorServer-side error

​
Common Errors

​
Missing company_id

// 400
{ "error": "company_id query parameter is required" }

​
Invalid API key

// 401
{ "error": "Invalid API key" }

​
Insufficient permissions

// 403
{ "error": "Insufficient permissions. Write access required." }

​
Resource not found

// 404
{ "error": "Customer not found" }

​
Missing required fields

// 400
{ "error": "name is required" }

​
Invalid status value

// 400
{ "error": "Invalid status. Must be one of: draft, sent, viewed, paid, overdue, cancelled" }

​
Business rule violations

// 400
{ "error": "Cannot delete a paid invoice" }

​
Best Practices

  • Always check the HTTP status code before parsing the response body
  • Use the error message for debugging, not for programmatic logic
  • Implement retry logic with exponential backoff for 500 errors
  • Log error responses for troubleshooting