Error Reference

All API errors return a consistent JSON format with an error field.

Error format

{
  "error": "Human-readable error message"
}

HTTP status codes

Status	Meaning	When it happens
400	Bad Request	Missing required fields, invalid data, or validation failure
401	Unauthorized	Missing, invalid, revoked, or expired API key
403	Forbidden	API key doesn't have the required scope
404	Not Found	Resource doesn't exist or doesn't belong to your business
429	Too Many Requests	Plan limit reached (API keys or webhook endpoints)
500	Internal Server Error	Something went wrong on our end

Common errors

Authentication errors (401)

// Missing header
{ "error": "Missing Authorization header" }

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

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

// Expired
{ "error": "API key has expired" }

Fix: Check that your Authorization header is formatted as Bearer oim_... and that the key is active and not expired.

Permission errors (403)

{ "error": "Insufficient permissions. Required: write" }

Fix: Your API key's scope doesn't allow this operation. Create a new key with the appropriate scope (e.g., write for creating resources).

Validation errors (400)

// Missing fields
{ "error": "Missing required fields: customer_id, items (at least one)" }

// Invalid items
{ "error": "Each item requires: description, quantity, unit_price" }

// No valid update fields
{ "error": "No valid fields to update" }

Fix: Check the required fields for the endpoint you're calling. See the individual API reference pages.

Not found errors (404)

{ "error": "Invoice not found" }
{ "error": "Customer not found" }
{ "error": "Business not found" }

Fix: Verify the resource ID is correct and belongs to the business associated with your API key.

Rate limit errors (429)

{ "error": "API key limit reached for your current plan" }

Fix: Upgrade your plan or delete unused API keys.

Debugging tips

1. Check the response status code — it tells you the category of error
2. Read the error message — it's always human-readable and specific
3. Verify your API key — most issues are authentication-related
4. Check the request body — ensure JSON is valid and required fields are present
5. Validate UUIDs — customer_id and resource IDs must be valid UUIDs

Rate limits by plan

Resource	Basic	Pro
API Keys	2	20
Webhook Endpoints	2	50
Webhook Deliveries	100/hour	5,000/hour
API Requests	100/min	1,000/min