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

# Error Handling

> Learn about Invaro API error codes and handling

When an error occurs, the API will return an appropriate HTTP status code along with a JSON response containing error details.

## Error Response Format

All error responses follow this format:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": "Additional error details when available"
  }
}
```

## Common Error Codes

| Code                    | Description                                     | HTTP Status |
| ----------------------- | ----------------------------------------------- | ----------- |
| UNAUTHORIZED            | Authentication failed                           | 401         |
| INVALID\_REQUEST        | Malformed request                               | 400         |
| CORRUPT\_DOCUMENT       | PDF document is invalid or corrupt              | 400         |
| UPLOAD\_ERROR           | File upload failures                            | 400/500     |
| RATE\_LIMIT\_EXCEEDED   | Too many requests                               | 429         |
| VALIDATION\_ERROR       | Request validation failed                       | 400         |
| SCHEMA\_NOT\_FOUND      | Schema with the specified ID does not exist     | 404         |
| SCHEMA\_EXISTS          | Active schema with the same name already exists | 409         |
| INVALID\_SCHEMA\_TYPE   | Invalid schema type specified                   | 400         |
| SCHEMA\_ERROR           | General schema operation error                  | 500         |
| INTERNAL\_SERVER\_ERROR | Server error                                    | 500         |

## Example Error Scenarios

### Authentication Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key provided"
  }
}
```

### Rate Limit Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests"
  }
}
```

### Validation Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid file type",
    "details": "Only PDF, JPG, JPEG, and PNG files are allowed"
  }
}
```

### Corrupt Document Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "CORRUPT_DOCUMENT",
    "message": "Some files failed to upload",
    "details": "PDF document is invalid: document appears to be corrupt or invalid"
  }
}
```

## Error Categories

<CardGroup>
  <Card title="Retryable Errors" icon="rotate-right">
    These errors are temporary and can be resolved by retrying the request after a delay:

    * **Rate Limit (429)**
      Exceeded request limits

    * **Gateway Errors**
      * Bad Gateway (502)
      * Service Unavailable (503)
      * Gateway Timeout (504)

    * **Processing Failures**
      Temporary processing issues
  </Card>

  <Card title="Non-Retryable Errors" icon="circle-xmark">
    These errors require fixes before retrying:

    * **Authentication (401, 403)**
      Invalid or unauthorized API key

    * **Validation (400)**
      Invalid request parameters

    * **Not Found (404)**
      Resource doesn't exist

    * **Processing Failures**
      Permanent processing errors
  </Card>
</CardGroup>

## HTTP Status Codes

<ResponseField name="2xx" type="number">
  Successful requests

  <Expandable title="details">
    * `200` OK - Request succeeded
    * `201` Created - Resource was created successfully
    * `202` Accepted - Request accepted for processing
  </Expandable>
</ResponseField>

<ResponseField name="4xx" type="number">
  Client errors

  <Expandable title="details">
    * `400` Bad Request - Invalid request format
    * `401` Unauthorized - Invalid API key
    * `403` Forbidden - Valid API key but insufficient permissions
    * `404` Not Found - Resource not found
    * `409` Conflict - Resource conflict
    * `429` Too Many Requests - Rate limit exceeded
  </Expandable>
</ResponseField>

<ResponseField name="5xx" type="number">
  Server errors

  <Expandable title="details">
    * `500` Internal Server Error - Server error
    * `502` Bad Gateway - Invalid response from upstream server
    * `503` Service Unavailable - Service temporarily unavailable
    * `504` Gateway Timeout - Request timeout
  </Expandable>
</ResponseField>

## Error Handling Best Practices

### 1. Check Success Flag

Always check the `success` field in the response:

```javascript theme={null}
const response = await api.processDocument(fileId);
if (!response.success) {
  // Handle error
  console.error(response.error.message);
  return;
}
```

### 2. Implement Retry Logic

Implement exponential backoff for retryable errors:

```javascript theme={null}
async function makeRequestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fn();
      return response;
    } catch (error) {
      if (!isRetryableError(error) || i === maxRetries - 1) {
        throw error;
      }
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

function isRetryableError(error) {
  return [
    429, // Rate limit
    502, // Bad gateway
    503, // Service unavailable
    504  // Gateway timeout
  ].includes(error.status);
}
```

### 3. Handle Rate Limits

Respect rate limit headers and implement backoff:

```javascript theme={null}
function handleRateLimit(error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    const retryAfter = error.retry_after || 1;
    return new Promise(resolve => {
      setTimeout(resolve, retryAfter * 1000);
    });
  }
  throw error;
}
```

### 4. Log Errors

Implement proper error logging:

```javascript theme={null}
function logError(error) {
  const errorInfo = {
    code: error.code,
    message: error.message,
    timestamp: new Date().toISOString(),
    requestId: error.requestId
  };
  console.error('API Error:', errorInfo);
}
```

## Support

If you encounter persistent errors or need assistance:

* Email: [support@invaro.ai](mailto:support@invaro.ai)
* Status Page: [status.invaro.ai](https://status.invaro.ai)