API Error Handling

API Error Handling

The Lockwave API returns consistent JSON error responses.

Error Format

All errors follow this structure:

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."]
  }
}

The errors object is only present for validation errors (422).

Status Codes

Code	Meaning	Action
400	Bad request	Check your request body and headers
401	Unauthenticated	Check your Bearer token
403	Forbidden	You lack permission for this action
404	Not found	The resource does not exist or is in a different team
422	Validation error	Check the errors object for field-specific messages
429	Rate limited	Wait and retry after the Retry-After seconds
500	Server error	Contact support if persistent

Rate Limiting

When rate limited, the response includes:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

Retry Strategy

For rate limiting (429) and server errors (500, 502, 503), use exponential backoff:

1. Wait 1 second, retry
2. Wait 2 seconds, retry
3. Wait 4 seconds, retry
4. Stop after 3 retries

Common Errors

• "No team context" (422) - Set the X-Team-Id header or ensure your account has a current team
• "You are not a member of the specified team" (403) - The team UUID in X-Team-Id is wrong or you were removed
• "This action is unauthorized" (403) - Your role lacks the required permission (e.g. member trying to delete a host)