Errors & Conventions

Content type

All endpoints accept and return application/json. Send a Content-Type: application/json header on any request with a body.

Response envelope

Most endpoints return a result envelope with a boolean success flag, a human-readable message, and a resource field named after the operation (leads, job, …). On failure the resource field is null:

{
  "success": true,
  "message": "Leads added successfully",
  "leads": [ /* ... */ ]
}

{
  "success": false,
  "message": "At least one lead must be provided",
  "leads": null
}

Common error messages

Situation	message
Missing auth header	Authorization header missing
Bad / expired token	Invalid or expired authentication token
Malformed body	Invalid request format: ...
Cross-project resource	... does not belong to your project
Server / database error	Failed to ...: ...

Status codes

Code	Meaning
200	Success.
400	Invalid request format or validation failure.
401	Missing/invalid token, or resource belongs to another project.
404	Resource not found within your project.
500	Unexpected server error.

note

Some endpoints signal validation failures inside a 200 response envelope (success: false) rather than with a 4xx status. Always check the success flag in addition to the HTTP status.