Errors

Errors are JSON with a human-readable error string and, sometimes, more fields:

{ "error": "Validation failed", "code": "…", "details": [ … ] }

Field	Present	Meaning
error	Always	What went wrong. Safe to log; do not parse it.
code	Some 4xx errors	A stable machine-readable reason. Branch on this when present.
details	Validation errors	Per-field problems (below).

Some errors add context fields, for example required_permission on a 403 or feature and current_plan on a 402.

Validation errors (400)

When the body, query or path parameters fail validation:

{
  "error": "Validation failed",
  "details": [
    { "field": "email", "message": "Invalid email", "code": "invalid_string" },
    { "field": "limit", "message": "Number must be less than or equal to 100", "code": "too_big" }
  ]
}

field is the dotted path to the offending value (address.city, items.0.price); code is the validator’s issue code (invalid_type, too_small, too_big, invalid_string, invalid_enum_value, custom, …). Other 400 responses carry only error, for example {"error":"Invalid ID format"}.

Status codes

Status	Meaning	Example body
400	The request is malformed or fails validation.	{"error":"Validation failed","details":[…]}
401	Missing, invalid or expired credentials. See Authentication.	{"error":"Authentication required"}
402	The organization’s plan does not include the feature.	{"error":"plan_upgrade_required","feature":"…","current_plan":"…"}
403	The user’s role lacks the permission, or the key lacks the scope.	{"error":"Forbidden","required_permission":"leads.delete"}
404	The record does not exist in your organization, or the endpoint does not exist.	Unknown route: {"error":"Not found","message":"The requested endpoint does not exist."}; missing record: {"error":"<Resource> not found"}
409	The request conflicts with the current state (for example a duplicate).	{"error":"…"}
429	Rate limit exceeded. See Rate limits.	{"error":"Too many requests, please try again later."}
500	Something failed on our side.	{"error":"Internal server error"}

A 500 never includes a stack trace or internal details. Records that belong to another organization are not visible to you and are reported as 404.

Handling errors

• Treat 4xx as a problem with the request: fix it before retrying. The exception is 429 — wait and retry.
• Retry 5xx and network errors with exponential backoff. For creates, make the operation safe to repeat on your side first (for example, look the record up before creating it again).
• Log error, the status code and the request path. Never log the Authorization header.