Errors

Status codes

Code	Meaning	When you'll see it
200	OK	Request succeeded.
201	Created	Resource was created.
204	No Content	Success, no body returned (e.g. DELETE).
400	Bad Request	The request is malformed.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	The key is valid but not allowed for this action.
404	Not Found	Resource doesn't exist.
409	Conflict	e.g. duplicate resource.
422	Unprocessable Entity	Validation failed.
429	Too Many Requests	You've hit the rate limit.
500	Server Error	Something went wrong on our end.

Error response shape

All error responses share a common JSON shape:

{
  "message": "A short, human-readable summary.",
  "errors": {
    "email": ["The email field is required."]
  }
}

The errors object is only included for 422 validation responses.

422 — Validation

Returned when the request body fails validation rules.

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

401 — Unauthenticated

{
  "message": "Unauthenticated."
}

403 — Forbidden

The token is valid but the user is not allowed to perform this action.

{
  "message": "This action is unauthorized."
}

403 from the `verified` middleware

Bulk writers (/transactions/sync, /import/store, /import/kuda/store) require a verified email. The response includes a hint so the SPA can show a verification banner:

{
  "message": "Your email address is not verified.",
  "requires_verified_email": true
}

404 — Not Found

{
  "message": "The requested resource was not found."
}

500 — Server Error

{
  "message": "Something went wrong on our end. Please try again."
}

Retry 5xx responses using exponential backoff. If the issue persists, contact support with the request ID from the response headers.