Skip to content

HTTP Error Codes

The Werk24 API uses standard HTTP status codes to indicate the success or failure of API requests. Understanding these codes helps you build robust error handling into your applications.

Error Response Format

All error responses follow a consistent JSON structure:

1
2
3
4
5
6
7
8
9
{
  "code": "400",
  "message": "Invalid ask type specified",
  "details": {
    "invalid_asks": ["INVALID_ASK"],
    "valid_asks": ["VARIANT_MEASURES", "VARIANT_GDTS", "TITLE_BLOCK"]
  },
  "request_id": "123e4567-e89b-12d3-a456-426614174000"
}

Fields:

  • code: HTTP status code or application-specific error code
  • message: Human-readable error description
  • details: Additional context (validation errors, supported values, etc.)
  • request_id: Unique identifier for debugging and support

Status Codes

2xx Success

Code Name Description
200 OK Request succeeded
201 Created Resource created successfully

4xx Client Errors

400 Bad Request

When it occurs: The request contains invalid data, malformed input, or violates validation rules.

Common causes:

  • Invalid ask types
  • Empty ask list
  • Malformed request parameters
  • Invalid field values

Example response:

1
2
3
4
5
6
7
8
9
{
  "code": "400",
  "message": "Invalid ask type specified",
  "details": {
    "invalid_asks": ["INVALID_ASK"],
    "valid_asks": ["VARIANT_MEASURES", "VARIANT_GDTS", "TITLE_BLOCK"]
  },
  "request_id": "req-123"
}

How to fix:

  • Validate ask types against the supported asks
  • Ensure all required fields are provided
  • Check field formats match the API specification

401 Unauthorized

When it occurs: Authentication fails due to invalid, expired, or missing credentials.

Common causes:

  • Invalid API token
  • Expired token
  • Missing authentication header
  • Incorrect region

Example response:

1
2
3
4
5
6
7
8
{
  "code": "401",
  "message": "Authentication failed",
  "details": {
    "reason": "token_expired"
  },
  "request_id": "req-456"
}

How to fix:

  • Verify your API token is valid
  • Check token hasn't expired
  • Ensure you're using the correct region
  • Contact support@werk24.io if issues persist

403 Forbidden

When it occurs: The authenticated user lacks permission for the requested resource.

Common causes:

  • Insufficient account permissions
  • Feature not available in your tier
  • Resource access restricted

How to fix:

  • Check your account tier and permissions
  • Upgrade your plan if needed
  • Contact support for access requests

404 Not Found

When it occurs: The requested resource doesn't exist.

Common causes:

  • Invalid resource ID
  • Resource has been deleted
  • Incorrect endpoint URL

How to fix:

  • Verify the resource ID is correct
  • Check the endpoint URL
  • Ensure the resource hasn't been deleted

415 Unsupported Media Type

When it occurs: The uploaded file format is not supported.

Common causes:

  • Unsupported file format (e.g., DWG, DXF)
  • Corrupted file
  • Encrypted PDF

Example response:

1
2
3
4
5
6
7
8
9
{
  "code": "415",
  "message": "Unsupported file format",
  "details": {
    "provided_format": "dwg",
    "supported_formats": ["PDF", "PNG", "JPEG", "TIFF"]
  },
  "request_id": "req-789"
}

How to fix:

  • Convert to a supported format (PDF, PNG, JPEG, TIFF)
  • See Supported File Formats
  • Ensure file isn't corrupted or encrypted

429 Too Many Requests

When it occurs: You've exceeded the API rate limit.

Common causes:

  • Too many requests in a short time period
  • Concurrent request limit exceeded
  • Account quota reached

Example response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "code": "429",
  "message": "Rate limit exceeded",
  "details": {
    "retry_after": 60,
    "limit": 1000,
    "current": 1000
  },
  "request_id": "req-abc"
}

How to fix:

  • Wait for the retry_after period (in seconds)
  • Implement exponential backoff
  • Reduce request frequency
  • Consider upgrading your plan for higher limits

5xx Server Errors

500 Internal Server Error

When it occurs: The server encountered an unexpected error.

Common causes:

  • Server-side bug
  • Database connection issue
  • Unexpected data format

Example response:

1
2
3
4
5
6
{
  "code": "500",
  "message": "Internal server error",
  "details": {},
  "request_id": "req-def"
}

How to fix:

  • The Werk24 team has been automatically notified
  • Retry your request after a short delay
  • If the problem persists, contact support@werk24.io with your request_id

503 Service Unavailable

When it occurs: The service is temporarily unavailable.

Common causes:

  • Scheduled maintenance
  • System overload
  • Temporary infrastructure issue

Example response:

1
2
3
4
5
6
7
8
{
  "code": "503",
  "message": "Service temporarily unavailable",
  "details": {
    "retry_after": 30
  },
  "request_id": "req-ghi"
}

How to fix:

  • Wait for the retry_after period (in seconds)
  • Retry your request
  • Check System Status for maintenance windows

Python Client Exception Classes

The werk24-python client library provides specific exception classes for each error type:

W24AuthenticationError (401)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from werk24 import W24AuthenticationError

try:
    async with Werk24Client(token="your_token") as client:
        # API calls
        pass
except W24AuthenticationError as e:
    print(f"Authentication failed: {e.error_code}")
    print(f"Details: {e.error_details}")
    print(f"Request ID: {e.request_id}")

W24ValidationError (400)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from werk24 import W24ValidationError

try:
    # API call with invalid parameters
    pass
except W24ValidationError as e:
    if "invalid_asks" in e.error_details:
        print(f"Invalid asks: {e.error_details['invalid_asks']}")
    if "valid_asks" in e.error_details:
        print(f"Valid asks: {e.error_details['valid_asks']}")

W24RateLimitError (429)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import asyncio
from werk24 import W24RateLimitError

try:
    # API call
    pass
except W24RateLimitError as e:
    wait_time = e.retry_after or 60
    print(f"Rate limited. Retrying after {wait_time}s...")
    await asyncio.sleep(wait_time)
    # Retry request

W24ServerError (500/503)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
from werk24 import W24ServerError

try:
    # API call
    pass
except W24ServerError as e:
    if e.is_transient:
        # 503 - Service temporarily unavailable
        wait_time = e.error_details.get("retry_after", 30)
        print(f"Service unavailable. Retry after {wait_time}s")
    else:
        # 500 - Internal server error
        print(f"Server error. Request ID: {e.request_id}")
        # Don't retry, contact support

Best Practices

1. Always Check Status Codes

1
2
3
4
5
6
7
import aiohttp

async with aiohttp.ClientSession() as session:
    async with session.post(url, json=data) as response:
        if response.status != 200:
            error_data = await response.json()
            # Handle error based on status code

2. Implement Retry Logic

Use exponential backoff for transient errors (429, 503):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import asyncio

async def api_call_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            # API call
            return result
        except (W24RateLimitError, W24ServerError) as e:
            if attempt == max_retries - 1:
                raise

            if isinstance(e, W24RateLimitError):
                wait_time = e.retry_after or (2 ** attempt)
            elif e.is_transient:
                wait_time = e.error_details.get("retry_after", 2 ** attempt)
            else:
                raise  # Don't retry permanent errors

            await asyncio.sleep(wait_time)

3. Log Request IDs

Always log request_id for debugging:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import logging

logger = logging.getLogger(__name__)

try:
    # API call
    pass
except (W24AuthenticationError, W24ValidationError, 
        W24RateLimitError, W24ServerError) as e:
    logger.error(
        f"API error: {e.error_code}",
        extra={
            "request_id": e.request_id,
            "error_details": e.error_details
        }
    )

4. Handle Validation Errors Gracefully

Provide helpful feedback for validation errors:

1
2
3
4
5
6
7
8
9
try:
    # API call
    pass
except W24ValidationError as e:
    if "invalid_asks" in e.error_details:
        invalid = e.error_details["invalid_asks"]
        valid = e.error_details.get("valid_asks", [])
        print(f"Invalid ask types: {', '.join(invalid)}")
        print(f"Valid ask types: {', '.join(valid[:5])}")

Troubleshooting

Common Issues

"Authentication failed" but token looks correct

  • Verify you're using the correct region
  • Check token hasn't expired
  • Ensure no extra whitespace in token

"Rate limit exceeded" immediately

  • Check for concurrent requests from multiple processes
  • Verify you're not in a retry loop
  • Consider implementing request queuing

"Service unavailable" persists

  • Check System Status
  • Verify your network connectivity
  • Contact support if issue continues

Getting Help

If you encounter persistent errors:

  1. Note the request_id from the error response
  2. Check System Status
  3. Review this documentation
  4. Contact support@werk24.io with your request_id

See Also