Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt

Use this file to discover all available pages before exploring further.

The Vendaze API uses standard HTTP status codes and returns a consistent error format on every failure.

​
Error format

{
  "error": {
    "code": "not_found",
    "message": "Person not found.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
FieldDescription
codeMachine-readable error code. Use in error handling logic.
messageHuman-readable description for developers. Do not show to end users.
request_idUnique request ID. Include when contacting support.
A 2xx response never contains error. A non-2xx response always contains error.

​
HTTP status codes

StatusMeaning
200Success. Resource read or updated.
201Created successfully.
204No content. Resource deleted. Empty body.
400Malformed request or missing required parameter.
401Unauthenticated. Token missing, invalid, or expired.
403Forbidden. Valid token but insufficient scope.
404Not found. Resource does not exist, was deleted, or belongs to another workspace.
422Validation failed. See the fields object.
429Rate limit exceeded.
500Internal error. Something went wrong on the server.

​
Error code reference

CodeHTTPWhen it occurs
unauthorized401Bearer token missing or signature invalid.
token_expired401Access token expired. Refresh using the refresh token.
insufficient_scope403Token lacks the required scope for this endpoint.
forbidden403Authenticated but not allowed to access this resource.
not_found404Resource does not exist, was deleted, or belongs to another workspace.
validation_error422Input failed validation. See fields for details.
rate_limit_exceeded429Too many requests. Wait the time indicated by Retry-After.
internal_error500Unexpected error. Use request_id when contacting support.

​
Validation errors

When validation fails, the response includes a fields object mapping each field to its problem: 
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed.",
    "fields": {
      "per_page": "Must be at most 100.",
      "due_date": "Invalid ISO 8601 date format."
    },
    "request_id": "uuid"
  }
}

​
Error handling in code

async function apiCall(url, options) {
  const res = await fetch(url, options);

  if (!res.ok) {
    const { error } = await res.json();

    switch (error.code) {
      case 'token_expired':
        await refreshAccessToken();
        return apiCall(url, options);

      case 'rate_limit_exceeded': {
        const retryAfter = parseInt(res.headers.get('Retry-After') ?? '60');
        await new Promise((r) => setTimeout(r, retryAfter * 1000));
        return apiCall(url, options);
      }

      case 'not_found':
        return null;

      default:
        throw new Error(`${error.code}: ${error.message} (request_id: ${error.request_id})`);
    }
  }

  return res.json();
}