Error Handling

All API errors follow a consistent JSON structure.

Error Response Format

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": [
      "The field name is required."
    ]
  }
}

HTTP Status Codes

Code	Meaning	Common Cause
200	OK	Request succeeded
201	Created	Resource(s) created successfully
302	Redirect	Dashboard form submission succeeded (redirects back)
401	Unauthorized	Missing or invalid authentication token/session
403	Forbidden	Token lacks required scope or user lacks permission
404	Not Found	Resource does not exist or is not within your account scope
422	Validation Error	Request body failed validation rules
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Validation Errors (422)

When request validation fails, the response includes field-level error messages:

{
  "message": "The given data was invalid.",
  "errors": {
    "leads.0.phone": ["The leads.0.phone field is required."],
    "leads.0.products": ["The leads.0.products field is required."]
  }
}

For bulk operations, error keys reference the array index (e.g., leads.0.phone, orders.2.city).

Authorization Errors (403)

Returned when the authenticated token does not have the required scope:

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

Common causes:

• API token missing the required permission (e.g., CREATE LEADS)
• User's role does not have the required policy permission
• Attempting to access a resource outside your account scope

Authentication Errors (401)

{
  "message": "Unauthenticated."
}

Common causes:

• Missing Authorization: Bearer {token} header
• Expired or revoked token
• Invalid token string

Bulk Operation Errors

For bulk create endpoints (leads, orders), partial failures are not supported. If any item in the array fails validation, the entire request is rejected with 422 and all validation errors are returned.

TIP

Validate your data client-side before sending bulk requests to avoid rejections.