Error Codes & Troubleshooting

The Finance API returns RFC-7807 compliant error structures with descriptive status messages.

Standard Error Response Format

{
  "statusCode": 409,
  "statusMessage": "409 Conflict: Entity 'movement:mov-coto-101' already has revision 1 with different content."
}

HTTP Status Codes Reference

HTTP Code	Name	Cause	Resolution Flow
400	Bad Request	Missing request body or invalid parameters.	Verify JSON payload structure and parameter names.
401	Unauthorized	Missing API Key or invalid session credentials.	Check X-API-Key or Authorization: Bearer <key> header.
403	Forbidden	Authenticated identity is not nicolasdelauretis122@gmail.com.	Log in with the authorized Google administrator account.
404	Not Found	Requested entity ID does not exist or was soft-deleted.	Verify entity identifier and ensure it has not been purged.
409	Conflict	CAS revision collision or request ID payload discrepancy.	Increment revision number or retrieve current state first.
413	Payload Too Large	Batch exceeds 50 items.	Split ingestion payload into batches of at most 50 events.
422	Unprocessable Entity	Domain constraint violation (e.g. negative amount, missing category for confirmed expense).	Correct business data fields according to schema rules.
429	Too Many Requests	Rate limit exceeded.	Implement exponential backoff and retry after cooldown.
500	Internal Error	Database or Worker execution exception.	Inspect worker execution logs in Cloudflare dashboard.