Errors

The API returns consistent error responses with a code, message, and optional details. Use the x-request-id header when contacting support for debugging.

Error Response Format

All errors follow this envelope:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters.",
    "details": {
      "fields": {
        "message": ["must be a non-empty string"]
      }
    }
  }
}

The details object is optional and may include field-level validation errors.

Error Codes

Full reference of all error codes, HTTP status, and descriptions:

Code	HTTP Status	Description
`API_KEY_MISSING`	401	Missing Authorization header. Use: Authorization: Bearer cs_live_...
`API_KEY_INVALID`	401	Invalid API key. Check your key and try again.
`API_KEY_EXPIRED`	401	API key has expired. Generate a new key from your dashboard.
`API_KEY_REVOKED`	401	API key has been revoked.
`API_KEY_SCOPE_INSUFFICIENT`	403	API key lacks the required scope for this operation.
`PLAN_UPGRADE_REQUIRED`	403	Your plan does not include access to this endpoint. Upgrade at chatspark.io/pricing
`TEAM_ROLE_INSUFFICIENT`	403	Your team role does not permit this operation.
`AGENT_ACCESS_DENIED`	403	This API key is restricted to specific agents and does not include the requested agent.
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded. Check X-RateLimit-* headers for details.
`AGENT_NOT_FOUND`	404	Agent not found.
`RESOURCE_NOT_FOUND`	404	The requested resource was not found.
`VALIDATION_ERROR`	400	Invalid request parameters.
`IDEMPOTENCY_CONFLICT`	409	Idempotency-Key was already used with different request parameters.
`CREDITS_EXHAUSTED`	402	Monthly message limit reached.
`STREAMING_ERROR`	500	An error occurred during response streaming.
`INTERNAL_ERROR`	500	An internal server error occurred.

Debugging with x-request-id

Every response includes an x-request-id header, a unique identifier for the request. Include it when reporting issues or contacting support to help us trace the request.

javascript

const res = await fetch("https://chatspark.io/api/v1/agents/ag_123/chat", {
  method: "POST",
  headers: {
    "Authorization": "Bearer cs_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Hello" }),
});

const requestId = res.headers.get("x-request-id");
const data = await res.json();

if (!res.ok) {
  console.error(`Request ${requestId} failed:`, data.error);
  // Use requestId when contacting support
}

Handling Errors in JavaScript

A practical example of parsing and handling API errors:

javascript

async function sendMessage(agentId, message) {
  const res = await fetch(`https://chatspark.io/api/v1/agents/${agentId}/chat`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.CHATSPARK_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message }),
  });

  const data = await res.json();
  const requestId = res.headers.get("x-request-id");

  if (!res.ok) {
    const { code, message, details } = data.error || {};
    switch (code) {
      case "API_KEY_MISSING":
      case "API_KEY_INVALID":
      case "API_KEY_EXPIRED":
      case "API_KEY_REVOKED":
        throw new Error("Authentication failed: " + message);
      case "RATE_LIMIT_EXCEEDED":
        const retryAfter = res.headers.get("Retry-After") || 60;
        throw new Error(`Rate limited. Retry after ${retryAfter}s (request-id: ${requestId})`);
      case "CREDITS_EXHAUSTED":
        throw new Error("Monthly message limit reached. Upgrade your plan.");
      case "VALIDATION_ERROR":
        throw new Error("Invalid request: " + (details?.fields ? JSON.stringify(details.fields) : message));
      default:
        throw new Error(`API error: ${code || res.status} - ${message} (request-id: ${requestId})`);
    }
  }

  return data;
}

Rate Limits

Pagination