Error Handling

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

HTTP Status Codes

Code	Meaning
200	Success
201	Resource created
204	Success with no content (DELETE)
400	Bad request
401	Unauthenticated — missing or invalid token
403	Forbidden — insufficient permissions
404	Resource not found
422	Validation error
429	Rate limit reached
500	Server error

Error Format

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "status": ["The selected status is invalid."]
  },
  "code": 422
}

Validation Errors (422)

Validation errors include an errors object with the failing fields:

curl -X POST https://app.beeving.com/api/v1/contacts \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "invalid-email"}'

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email must be a valid email address."]
  },
  "code": 422
}

Rate Limiting (429)

{
  "message": "Too Many Attempts.",
  "errors": null,
  "code": 429
}

Check the response headers for quota information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
Retry-After: 30

Best Practices

• Always check the HTTP status code before processing the response
• On 429, wait for the duration indicated by Retry-After
• Log 5xx errors to detect server-side incidents