Error Codes

When a request fails the SilentChat API returns a JSON error response with a consistent structure. This page documents the response format, all error codes, and the HTTP status codes used.

Error Response Format

Every error response has the following shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'email' field must be a valid email address.",
    "status": 400
  }
}

Field	Type	Description
`error.code`	`string`	A machine-readable error code (see table below).
`error.message`	`string`	A human-readable description of the error.
`error.status`	`number`	The HTTP status code.

Error Codes

Code	HTTP Status	Description
`AUTH_MISSING_TOKEN`	401	No authentication token or API key was provided.
`AUTH_INVALID_TOKEN`	401	The token is malformed, expired, or the signature is invalid.
`AUTH_TOKEN_REVOKED`	401	The token has been revoked (e.g. after a logout or password change).
`AUTH_INVALID_CREDENTIALS`	401	The email or password is incorrect.
`AUTH_EMAIL_NOT_VERIFIED`	403	The account’s email address has not been verified.
`FORBIDDEN`	403	The authenticated user does not have permission to perform this action.
`TENANT_REQUIRED`	400	The `X-Tenant-ID` header is missing and is required for this endpoint.
`TENANT_NOT_FOUND`	404	The specified tenant does not exist or you do not have access to it.
`VALIDATION_ERROR`	400	One or more fields in the request body failed validation.
`NOT_FOUND`	404	The requested resource does not exist.
`CONFLICT`	409	The request conflicts with the current state (e.g. duplicate email, domain already added).
`RATE_LIMITED`	429	Too many requests. Check the `Retry-After` header.
`WIDGET_KEY_INVALID`	401	The widget key is not recognised or has been revoked.
`WIDGET_DOMAIN_NOT_ALLOWED`	403	The widget is being loaded from a domain that is not in the allowed domains list.
`FILE_TOO_LARGE`	400	The uploaded file exceeds the maximum size limit.
`PLAN_LIMIT_EXCEEDED`	403	The action exceeds the limits of your current plan (e.g. max widgets, max agents).
`INTERNAL_ERROR`	500	An unexpected server error occurred. If the problem persists, contact support.

HTTP Status Codes

The API uses standard HTTP status codes. Here is a summary of the codes you may encounter:

Status	Meaning	When
`200`	OK	Request succeeded.
`201`	Created	Resource was created successfully.
`204`	No Content	Request succeeded with no response body (e.g. DELETE).
`400`	Bad Request	Invalid or missing parameters.
`401`	Unauthorized	Authentication failed or was not provided.
`403`	Forbidden	Authenticated but not permitted.
`404`	Not Found	Resource does not exist.
`409`	Conflict	Resource already exists or conflicts with current state.
`429`	Too Many Requests	Rate limit exceeded.
`500`	Internal Server Error	Unexpected server error.

Handling Errors in Code

const response = await fetch('https://api.silentchat.de/v1/conversations', {
  headers: {
    'Authorization': 'Bearer ' + accessToken,
    'Content-Type': 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case 'AUTH_INVALID_TOKEN':
      // Token expired - refresh and retry
      break;
    case 'RATE_LIMITED':
      // Wait and retry
      const retryAfter = response.headers.get('Retry-After');
      break;
    case 'VALIDATION_ERROR':
      // Fix request parameters
      console.error('Validation:', error.message);
      break;
    default:
      console.error(`API error [${error.code}]: ${error.message}`);
  }
}