Introduction

Error Handling

HTTP status codes, error formats, and best practices for handling API errors.

Error response format

All errors return a JSON body with success: false:

{
  "success": false,
  "message": "A human-readable description of the error.",
  "errors": {
    "email": ["The email field is required."],
    "phone": ["The phone has already been taken."]
  }
}

The errors field is only present for 422 Unprocessable Entity (validation errors).

HTTP status codes

Status	Name	When it occurs
`200`	OK	Request succeeded
`201`	Created	Resource was successfully created
`204`	No Content	Successful deletion (no body returned)
`400`	Bad Request	Malformed request body or query parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Inactive account or disallowed request origin
`404`	Not Found	Resource does not exist or does not belong to your account
`422`	Unprocessable Entity	Validation failed — see `errors` field
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Something went wrong on our end

Common errors

401 – Missing API key

{
  "success": false,
  "message": "Unauthenticated. Please provide a valid API key."
}

Fix: Include Authorization: Bearer <your_key> in every request.

422 – Validation error

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "phone": ["The phone must be a valid phone number."]
  }
}

Fix: Read the errors object for field-level details. Correct the offending fields and retry.

404 – Resource not found

{
  "success": false,
  "message": "Contact not found."
}

Fix: Verify the resource ID exists and belongs to your account.

429 – Rate limit exceeded

{
  "success": false,
  "message": "Too many requests. Please slow down.",
  "retry_after": 22
}

Fix: Wait retry_after seconds, then retry. See Rate Limits for guidance.

500 – Server error

{
  "success": false,
  "message": "An unexpected error occurred. Please try again later."
}

Fix: Retry after a short delay. If the issue persists, contact support.

For POST requests that create resources, the API is not currently idempotent by default. Avoid retrying 201 Created responses — you may create duplicate resources. For safe retries on message sending, check for existing messages first.

Rate Limits

Understand the SkyLight Chat API rate limits and how to handle throttling.

API Reference

Complete reference for all SkyLight Chat REST API v1 endpoints.