Error Handling

thelawin.dev uses standard HTTP status codes and detailed JSON error responses.

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request - Invalid input
401	Unauthorized - Invalid API key
403	Forbidden - Key doesn't have access
429	Too Many Requests - Rate limited
500	Server Error - Contact support

Error Response Format

All errors follow this structure:

{
  "error": "validation_failed",
  "message": "Invoice validation failed",
  "details": [
    {
      "path": "$.invoice.seller.vatId",
      "code": "REQUIRED",
      "message": "Seller VAT ID is required"
    }
  ]
}

Error Types

validation_failed

Input validation errors. Check the details array for specific issues.

{
  "error": "validation_failed",
  "details": [
    {
      "path": "$.invoice.number",
      "code": "REQUIRED",
      "message": "Invoice number is required"
    }
  ]
}

invalid_api_key

The provided API key is invalid or has been revoked.

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid"
}

quota_exceeded

Monthly quota has been reached.

{
  "error": "quota_exceeded",
  "message": "Monthly quota exceeded",
  "account": {
    "remaining": 0,
    "plan": "starter",
    "reset_at": "2026-02-01T00:00:00Z"
  }
}

rate_limited

Too many requests in a short time period.

{
  "error": "rate_limited",
  "message": "Rate limit exceeded",
  "retry_after": 60
}

JSON Path Format

Error paths use JSON Path notation to identify the exact field:

Path	Meaning
$.invoice.number	Invoice number field
$.invoice.seller.name	Seller's name
$.invoice.items[0].quantity	First item's quantity

Handling Errors in SDKs

TypeScript

const result = await client.invoice()
  .number('2026-001')
  .generate()

if (!result.success) {
  result.errors.forEach(error => {
    console.error(`${error.path}: ${error.message}`)
  })
}

Python

result = client.invoice().number("2026-001").generate()

if not result.success:
    for error in result.errors:
        print(f"{error.path}: {error.message}")

Best Practices

1. Always check for errors - Don't assume requests succeed
2. Log error details - Include the full error response for debugging
3. Handle rate limits - Implement exponential backoff
4. Validate before sending - Use client-side validation to catch errors early