Skip to main content
Every error response shares the same base shape: 
{
  "success": false,
  "status": "error",
  "message": "Company not found"
}
message is human-readable and may change over time. Most errors carry exactly these three fields — there is no top-level machine error code, statusCode, timestamp, or path field on a standard error. Branch on the HTTP status code, and on the more specific fields documented below where they apply.

​
Validation errors

Requests that fail schema validation return 400 with a Validation failed message and an errors array of per-field problems: 
{
  "success": false,
  "status": "error",
  "message": "Validation failed",
  "errors": [
    { "path": "email", "message": "Invalid email" },
    { "path": "password", "message": "String must contain at least 8 character(s)" }
  ]
}

​
File upload errors

Upload endpoints add a machine-readable error field on failures so you can branch programmatically: 
{
  "success": false,
  "message": "File size too large. Maximum size is 10MB.",
  "error": "FILE_SIZE_LIMIT_EXCEEDED"
}
errorStatusWhen
FILE_SIZE_LIMIT_EXCEEDED400Upload exceeded the endpoint’s size cap (10MB or 25MB depending on endpoint).
FILE_COUNT_LIMIT_EXCEEDED400Too many files in a multi-upload request.
UNEXPECTED_FILE_FIELD400A file was sent under an unexpected field name.
FILE_UPLOAD_FAILED400Generic upload failure — check the files and retry.
Requests whose body itself is too large (not via the upload fields) return 413 with "File size too large. Maximum allowed size is 50MB.". Malformed JSON returns 400 with "Invalid request format.".

​
Status codes

StatusMeaningRetry?
400Invalid input, failed validation, or a precondition failedNo — fix the request.
401Not authenticated, or the access token is missing/expiredRefresh the session and retry.
402Payment required (payment processing failed)No — resolve payment.
403Authenticated but not allowed, email not verified, or insufficient wallet creditsNo.
404Resource not found, or not owned by youNo.
409Conflict (resource already exists, race)Sometimes.
413Payload too largeNo — shrink it.
429Rate limit hitYes, after Retry-After. See Rate limits.
500Unhandled server errorYes, with exponential backoff.

​
Common conditions

The backend throws typed errors that map to these statuses. The message text varies; the status code is the stable signal.
ConditionStatusTypical message
Email not verified at login403”Please verify your email before logging in…” (response also carries data.requiresVerification: true).
Not authenticated401”Unauthorized”
Insufficient wallet credits403”Insufficient credits”
Resource not found404”Company not found”, “Webhook subscription not found”, etc.
Conflict / already exists409”Resource already exists”
Payment processing failed402”Payment processing failed”
Some endpoints attach extra context fields under data alongside the base shape (for example, login’s email-not-verified response includes data.requiresVerification and data.userId). Read the specific endpoint’s reference page for those.