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 in SCREAMING_SNAKE_CASE. Use this for programmatic error handling.
`error.message`	`string`	A human-readable message describing what went wrong. Safe to display to end users.
`error.status`	`number`	An optional object with additional context, such as field-level validation errors.

Error Codes

Code	HTTP Status	Description
`AUTH_MISSING_TOKEN`	401	No valid credentials were provided or the access token has expired.
`AUTH_INVALID_TOKEN`	401	The provided token is malformed or has an invalid signature.
`AUTH_TOKEN_REVOKED`	401	The JWT access token has expired. Refresh it using your refresh token.
`AUTH_INVALID_CREDENTIALS`	401	No valid credentials were provided or the access token has expired.
`AUTH_EMAIL_NOT_VERIFIED`	403	The authenticated user does not have permission to perform this action.
`FORBIDDEN`	403	The authenticated user does not have permission to perform this action.
`TENANT_REQUIRED`	400	One or more request fields failed validation. See details for field-level errors.
`TENANT_NOT_FOUND`	404	The requested resource does not exist or is not accessible.
`VALIDATION_ERROR`	400	One or more request fields failed validation. See details for field-level errors.
`NOT_FOUND`	404	The requested resource does not exist or is not accessible.
`CONFLICT`	409	The request conflicts with the current state of the resource (e.g. duplicate email).
`RATE_LIMITED`	429	Too many requests. Slow down and retry after the duration indicated in the Retry-After header.
`WIDGET_KEY_INVALID`	401	The webhook payload could not be verified. Check your signing secret.
`WIDGET_DOMAIN_NOT_ALLOWED`	403	The authenticated user does not have permission to perform this action.
`FILE_TOO_LARGE`	400	One or more request fields failed validation. See details for field-level errors.
`PLAN_LIMIT_EXCEEDED`	403	Your current plan does not allow this action. Upgrade to unlock this feature.
`INTERNAL_ERROR`	500	An unexpected server error occurred. If this 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	The request succeeded.
`201`	Created	A new resource was created successfully.
`204`	No Content	The request succeeded with no response body (e.g. after a DELETE).
`400`	Bad Request	The request was malformed or failed validation.
`401`	Unauthorized	Authentication is required or credentials are invalid.
`403`	Forbidden	The caller is authenticated but not authorised to perform the action.
`404`	Not Found	The resource was not found.
`409`	Conflict	The request conflicts with the current resource state.
`429`	Too Many Requests	The caller has exceeded the rate limit.
`500`	Internal Server Error	An unexpected server-side error occurred.

Handling Errors in Code

Always check the code field rather than the error message string — the message may change between releases, but error codes are stable.

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}`);
  }
}