Skip to main content

​
Errors and rate limits

All Fluide Suite services return a consistent JSON envelope. Use the code field for programmatic handling; use message for display.

​
Success envelope

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {}
}

​
Error envelope

{
  "success": false,
  "message": "Human-readable, localized text",
  "code": "VALIDATION_FAILED",
  "errors": { "from": ["from must be a valid date"] },
  "statusCode": 400,
  "timestamp": "2026-06-03T12:00:00.000Z"
}
FieldPurpose
codeStable machine-readable identifier — use this in client logic
messageLocalized text for humans (may change with locale)
errorsField-level validation details when code is VALIDATION_FAILED
statusCodeHTTP status (duplicated in body for logging)
timestampUTC ISO-8601 time of the error

​
Safe 500 responses

Server errors (5xx) always return a generic message and code: INTERNAL_ERROR. Internal details (stack traces, SQL, secrets) are never exposed in the response body. Include timestamp and endpoint details when contacting support.

​
Global error codes

CodeHTTPMeaningWhat to do
VALIDATION_FAILED400Request body or query failed validationFix fields in errors and retry
INTERNAL_ERROR500Unexpected server errorRetry with backoff; contact support with timestamp
HTTP_ERRORvariesGeneric HTTP error without a domain codeRead message; fix request or permissions

​
Authentication errors

CodeHTTPMeaningWhat to do
INVALID_CREDENTIALS401Email or password incorrectVerify credentials
DEVELOPER_KEYS_INVALID401API key or secret invalidCheck X-Fluide-Api-Key and X-Fluide-Api-Secret
GATEWAY_AUTH_REQUIRED401Missing gateway session headerCall through the Fluide API gateway
GATEWAY_AUTH_INVALID401Invalid session payloadRe-authenticate
NOT_AN_ORGANIZATION_MEMBER403User not in target organizationUse an account with membership
EMAIL_NOT_VERIFIED403Email not verifiedComplete verification flow

​
Product-specific codes

Each service maintains a registry in src/errors/<service>.error-codes.ts. After deploy, catalogs are merged into openapi/error-codes-merged.json via: 
node scripts/merge-error-codes.mjs

​
HR (examples)

CodeHTTPMeaning
USER_NOT_FOUND404HR user record not found
ATTENDANCE_INVALID_DATE_RANGE400Invalid from/to date range

​
Accounting / Books (examples)

CodeHTTPMeaning
JOURNAL_ENTRY_NOT_FOUND404Journal entry not found
JOURNAL_ENTRY_NOT_BALANCED400Debits and credits do not balance

​
Payroll (examples)

CodeHTTPMeaning
PAYROLL_RUN_NOT_FOUND404Payroll run not found
PAYROLL_RUN_LOCKED409Run cannot be modified in current status

​
Pay (examples)

CodeHTTPMeaning
PAYMENT_NOT_FOUND404Payment record not found
WALLET_INSUFFICIENT_BALANCE400Wallet balance too low
  • Never retry 401 blindly. Re-check headers and rotated secrets.
  • For 429 Too Many Requests, back off and retry with jitter.
  • Log code + timestamp in your integration for support tickets.

​
Support data

When contacting support, include:
  • Timestamp (UTC) from the error body
  • code and HTTP status
  • Endpoint + HTTP method
  • Request ID header if present