Error Handling

The API uses standard HTTP status codes. Every error body is JSON.

Status codes

Code	Meaning
200	Success
201	Resource created
204	Success, empty body (most DELETE calls)
401	Missing, invalid or expired token
403	The token is missing a permission, or the action is not allowed
404	Resource not found in your workspace
409	Conflict with the current state (for example a duplicate)
422	Validation error, or a business rule was violated
429	Rate limit reached
500	Server error

Error format

{
  "error": "ValidationError",
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."]
  },
  "code": 422
}

Field	Description
error	Machine-readable type: ValidationError, Unauthorized, Forbidden, HttpError, TooManyRequests, InternalServerError
message	Human-readable description
errors	Validation errors only: field → list of messages
code	HTTP status code

INFO

Responses from the authentication layer (401 and 403 for missing permissions) contain only error and message.

Validation errors (422)

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

{
  "error": "ValidationError",
  "message": "The email field must be a valid email address.",
  "errors": {
    "email": ["The email field must be a valid email address."]
  },
  "code": 422
}

Business rule errors also use 422, with no errors object. For example, deleting a pipeline stage that still has deals returns:

{
  "error": "HttpError",
  "message": "Cannot delete a stage that has deals. Move or delete the deals first.",
  "code": 422
}

Best practices

• Always send Accept: application/json.
• Branch on the HTTP status and on error, not on message: the wording of message can change.
• On 429, wait for the number of seconds in Retry-After before retrying. See Rate limiting.
• Retry 5xx errors with exponential backoff.