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:

{
  "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

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key provided"
  }
}

Rate Limit Error

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests"
  }
}

Validation Error

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

Corrupt Document Error

{
  "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

Retryable Errors

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

Non-Retryable Errors

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

HTTP Status Codes

2xx · number

Successful requests

Show details

• 200 OK - Request succeeded
• 201 Created - Resource was created successfully
• 202 Accepted - Request accepted for processing

4xx · number

Client errors

Show 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

5xx · number

Server errors

Show 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

Error Handling Best Practices

1. Check Success Flag

Always check the success field in the response:

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:

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:

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:

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: [e-mail]
• Status Page: status.invaro.ai