Errors & Rate Limits

Understanding API errors, status codes, and rate limiting behavior.

Error Response Format

When an error occurs, the API returns a JSON response with details about what went wrong. The response structure is consistent across all error types.

Standard Error Response

{
  "detail": "Authentication credentials were not provided."
}

Validation Error Response

Field-level validation errors include the field name:

{
  "email": ["Enter a valid email address."],
  "quantity": ["Ensure this value is greater than or equal to 1."]
}

Detailed Error Response

Some errors include additional context:

{
  "detail": "Not found.",
  "code": "not_found"
}

Error Codes

Spwig uses structured error codes to help you identify and handle specific error conditions programmatically. Error codes follow a consistent pattern.

Error Code Format

Error codes use a hierarchical format: {category}_{action}_{reason}

Reference IDs

For server errors (5xx), the API includes a unique reference ID in the format ERR-XXXXXX. Include this ID when contacting support to help identify the specific error in server logs.

{
  "detail": "An unexpected error occurred.",
  "reference": "ERR-A1B2C3"
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the result of a request:

Common Errors

{"detail": "Invalid token."}

{"detail": "You do not have permission to perform this action."}

{"detail": "Not found."}

{"quantity": ["Ensure this value is greater than or equal to 1."]}

{"detail": "A product with this SKU already exists."}

Rate Limiting

To ensure fair usage and protect the platform, the API enforces rate limits on requests. Rate limiting uses a dual-tier system with both burst (short-term) and sustained (long-term) limits. When you exceed either limit, you'll receive a 429 Too Many Requests response.

Rate Limit Tiers

Endpoint-Specific Limits

Some endpoints have additional rate limits to prevent abuse:

Rate Limit Headers

Every response includes headers to help you track your usage:

Rate Limit Response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067200
Retry-After: 45

{
  "detail": "Request was throttled. Expected available in 45 seconds."
}

Error Handling Best Practices

1. Check Status Codes First

Always check the HTTP status code before parsing the response body:

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
elif response.status_code == 429:
    retry_after = int(response.headers.get('Retry-After', 60))
    time.sleep(retry_after)
    # Retry the request
elif response.status_code >= 400:
    error = response.json()
    handle_error(response.status_code, error)

2. Implement Retry Logic

For transient errors (5xx, 429), implement retry with exponential backoff:

import time
from functools import wraps

def retry_with_backoff(max_retries=3, base_delay=1):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    response = func(*args, **kwargs)
                    if response.status_code < 500:
                        return response
                except requests.exceptions.RequestException:
                    pass

                delay = base_delay * (2 ** attempt)
                time.sleep(delay)

            raise Exception(f"Failed after {max_retries} retries")
        return wrapper
    return decorator

3. Log Errors with Context

Include relevant context when logging errors:

import logging

logger = logging.getLogger(__name__)

def handle_api_error(response, endpoint):
    logger.error(
        "API Error",
        extra={
            "status_code": response.status_code,
            "endpoint": endpoint,
            "response_body": response.text[:500],  # Truncate for safety
            "request_id": response.headers.get("X-Request-ID"),
        }
    )

4. Handle Validation Errors Gracefully

Parse field-level errors to provide helpful feedback:

def format_validation_errors(error_response):
    """Convert API validation errors to user-friendly messages."""
    messages = []
    for field, errors in error_response.items():
        for error in errors:
            messages.append(f"{field}: {error}")
    return messages

Deprecation Policy

We strive to maintain backward compatibility. When breaking changes are necessary, we follow a structured deprecation process.

Deprecation Timeline

• Announcement: Deprecated features are announced in release notes and API documentation at least 6 months before removal.
• Warning Headers: Deprecated endpoints return a Deprecation header with the sunset date.
• Sunset: After the deprecation period, endpoints return 410 Gone with migration guidance.

Deprecation Headers

HTTP/1.1 200 OK
Deprecation: Sun, 01 Jan 2025 00:00:00 GMT
Sunset: Sun, 01 Jul 2025 00:00:00 GMT
Link: </api/v1/products-v2/>; rel="successor-version"

Version Support

The Spwig API does not use URL-based versioning (e.g., /v1/, /v2/). Instead, the platform version is reflected in the OpenAPI specification. Each release maintains backward compatibility within its major version.