Error Codes Reference

The Vysion API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

2xx codes indicate success
4xx codes indicate an error that failed given the information provided (e.g., a required parameter was omitted, invalid API key, etc.)
5xx codes indicate an error with Vysion’s servers

Standard Error Response Format

All API errors follow this consistent response format:

{
  "error": {
    "code": 400,
    "message": "Detailed error description"
  }
}

HTTP Status Codes

2xx Success Codes

Code	Status	Description
`200`	OK	The request was successful

4xx Client Error Codes

Code	Status	Description
`400`	Bad Request	Your request is invalid. Check parameters and request format
`401`	Unauthorized	Your API key is missing or invalid
`403`	Forbidden	The requested resource is hidden for administrators only
`404`	Not Found	The specified resource could not be found
`405`	Method Not Allowed	You tried to access a resource with an invalid HTTP method
`406`	Not Acceptable	You requested a format that isn’t JSON
`410`	Gone	The requested resource has been removed from our servers
`418`	I’m a teapot	RFC 2324 - This should not occur in normal operation
`422`	Unprocessable Entity	The request was well-formed but contains semantic errors
`429`	Too Many Requests	You’re requesting too many resources! Rate limit exceeded

5xx Server Error Codes

Code	Status	Description
`500`	Internal Server Error	We had a problem with our server. Try again later
`503`	Service Unavailable	We’re temporarily offline for maintenance. Please try again later

Common Error Scenarios

{
  "error": {
    "code": 401,
    "message": "API key is required"
  }
}

{
  "error": {
    "code": 401,
    "message": "Invalid API key"
  }
}

Validation Errors

Missing Required Parameter
Invalid Parameter Value

{
  "error": {
    "code": 422,
    "message": "Validation Error",
    "detail": [
      {
        "loc": ["query", "q"],
        "msg": "field required",
        "type": "value_error.missing"
      }
    ]
  }
}

{
  "error": {
    "code": 422,
    "message": "Validation Error",
    "detail": [
      {
        "loc": ["query", "size"],
        "msg": "ensure this value is less than or equal to 100",
        "type": "value_error.number.not_le"
      }
    ]
  }
}

Rate Limiting Errors

{
  "error": {
    "code": 429,
    "message": "Too Many Requests - Rate limit exceeded. Please slow down your requests."
  }
}

Resource Not Found

Document Not Found
Endpoint Not Found

{
  "error": {
    "code": 404,
    "message": "Document not found with the specified ID"
  }
}

{
  "error": {
    "code": 404,
    "message": "The requested endpoint does not exist"
  }
}

Error Handling Best Practices

1. Always Check Status Codes

import requests

response = requests.get('https://api.vysion.ai/api/v1/documents',
                       headers={'X-API-Key': 'your-api-key'})

if response.status_code == 200:
    data = response.json()
    # Process successful response
elif response.status_code == 401:
    print("API key is invalid")
elif response.status_code == 429:
    print("Rate limit exceeded - waiting before retry")
else:
    print(f"Error {response.status_code}: {response.json()}")

2. Implement Retry Logic

For temporary errors (5xx codes and 429), implement exponential backoff:

import time
import random

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()
        elif response.status_code in [429, 500, 502, 503, 504]:
            if attempt < max_retries - 1:
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(wait_time)
                continue

        # For other errors, don't retry
        response.raise_for_status()

    raise Exception(f"Max retries exceeded")

3. Log Error Details

import logging

def handle_api_error(response):
    error_data = response.json().get('error', {})

    logging.error(f"API Error - Code: {error_data.get('code')}, "
                  f"Message: {error_data.get('message')}")

    # Log validation details if present
    if 'detail' in error_data:
        for detail in error_data['detail']:
            logging.error(f"Validation Error - Field: {detail.get('loc')}, "
                          f"Error: {detail.get('msg')}")

Error Message Enumeration

The API uses standardized error messages for common scenarios:

Message	Code	Description
“Bad Request”	400	General request format error
“Unauthorized”	401	Authentication failure
“Forbidden”	403	Access denied
“Not Found”	404	Resource doesn’t exist
“Conflict”	409	Resource conflict
“Unprocessable Entity”	422	Validation error
“Too Many Requests”	429	Rate limit exceeded
“Internal Server Error”	500	Server-side error

Monitoring and Alerting

Track Error Rates

Monitor the frequency of different error codes to identify issues:

High 4xx rates: May indicate client integration issues
High 5xx rates: May indicate server problems
429 errors: Rate limiting - consider reducing request frequency

Set Up Alerts

Configure alerts for:

Error rate exceeding normal thresholds
Consecutive 5xx errors
Authentication failures (potential security issues)