> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nullpass.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Error response format and status codes

<Warning>
  **Internal Documentation Only:** If you're not a Null Tools developer, you can close this documentation or visit the [Apps section](/apps/coming-soon) to learn more about using Null Pass in your applications.
</Warning>

## Error Response Format

All errors follow a consistent format:

```json theme={null}
{
  "error": "Error message description"
}
```

## Status Codes

<ResponseField name="200" type="OK">
  Request successful
</ResponseField>

<ResponseField name="201" type="Created">
  Resource created successfully (e.g., user registration)
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Validation error or invalid request format

  * Missing required fields
  * Invalid data format
  * Validation rule violations (e.g., password too short)
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Authentication required or failed

  * Missing Authorization header
  * Invalid or expired token
  * Invalid credentials
  * Invalid 2FA code
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Request blocked by security system

  * Rate limit exceeded (Arcjet)
  * Bot detected (Arcjet)
  * Shield protection triggered
</ResponseField>

<ResponseField name="404" type="Not Found">
  Resource not found

  * User not found
  * Session not found
  * Invalid endpoint
</ResponseField>

<ResponseField name="409" type="Conflict">
  Resource conflict

  * User already exists
  * Duplicate resource
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error

  * Database error
  * Unexpected exception
  * Configuration error
</ResponseField>

## Common Error Scenarios

### Validation Errors (400)

```json theme={null}
{
  "error": "Password must be at least 8 characters"
}
```

**Causes:**

* Invalid email format
* Password too short
* Missing required fields
* Invalid data types

### Authentication Errors (401)

```json theme={null}
{
  "error": "Invalid credentials"
}
```

**Causes:**

* Wrong email/password
* Expired token
* Invalid 2FA code
* Missing Authorization header

### Rate Limit Errors (403)

```json theme={null}
{
  "error": "Rate limit exceeded"
}
```

**Causes:**

* Too many requests in short time
* Bot detection triggered
* Shield protection activated

### Not Found Errors (404)

```json theme={null}
{
  "error": "User not found"
}
```

**Causes:**

* Invalid user ID
* Resource deleted
* Invalid endpoint path

## Error Handling Best Practices

<AccordionGroup>
  <Accordion title="Client-Side Handling" icon="code">
    ```javascript theme={null}
    try {
      const response = await fetch('/api/auth/login', {
        method: 'POST',
        body: JSON.stringify({ email, password })
      });
      
      if (!response.ok) {
        const error = await response.json();
        // Handle specific error types
        if (response.status === 401) {
          // Invalid credentials
        } else if (response.status === 403) {
          // Rate limited
        } else if (response.status === 400) {
          // Validation error
        }
        throw new Error(error.error);
      }
      
      const data = await response.json();
    } catch (error) {
      // Handle network or parsing errors
    }
    ```
  </Accordion>

  <Accordion title="Retry Logic" icon="arrow-rotate-right">
    Implement exponential backoff for:

    * 500 errors (server errors)
    * 403 errors (rate limits)
    * Network failures

    Don't retry:

    * 400 errors (validation - fix request)
    * 401 errors (authentication - re-authenticate)
    * 404 errors (not found - check resource)
  </Accordion>

  <Accordion title="Logging" icon="file-lines">
    Log all errors with:

    * Error message
    * Status code
    * Request details (without sensitive data)
    * Timestamp
    * User ID (if authenticated)
  </Accordion>
</AccordionGroup>

## Internal Error Logging

Errors are logged server-side with different levels:

* **Warn**: Validation errors, failed auth attempts
* **Error**: Server errors, unexpected exceptions
* **Info**: Successful operations, important events

Check application logs for detailed error information including stack traces for 500 errors.