Errors

When an API request fails, VisiHub returns an error response with an HTTP status code and a JSON body describing the problem.

Error response format

{
  "error": {
    "code": "not_found",
    "message": "The requested file does not exist."
  }
}

Error codes

400 Bad Request

Code	Description
invalid_request	The request body is malformed or missing required fields.
invalid_parameter	A query parameter or body field has an invalid value.
unsupported_format	The uploaded file format is not supported.

401 Unauthorized

Code	Description
unauthorized	No valid authentication token was provided.
token_expired	The JWT token has expired. Request a new magic link.

403 Forbidden

Code	Description
forbidden	The authenticated user does not have permission for this action.

404 Not Found

Code	Description
not_found	The requested resource does not exist.

409 Conflict

Code	Description
conflict	The request conflicts with the current state (e.g., duplicate name).

413 Payload Too Large

Code	Description
file_too_large	The uploaded file exceeds the maximum allowed size.

422 Unprocessable Entity

Code	Description
validation_error	The request was well-formed but contains invalid data. Check the message field for details.

429 Too Many Requests

Code	Description
rate_limited	Too many requests. Check X-RateLimit-Reset header for when to retry.

500 Internal Server Error

Code	Description
internal_error	An unexpected server error occurred. If this persists, contact support.

Handling errors

const response = await fetch('https://api.visihub.com/v1/files', {
  headers: { 'Authorization': `Bearer ${token}` },
});

if (!response.ok) {
  const { error } = await response.json();
  switch (error.code) {
    case 'unauthorized':
    case 'token_expired':
      // Re-authenticate
      break;
    case 'rate_limited':
      // Wait and retry
      const resetAt = response.headers.get('X-RateLimit-Reset');
      break;
    default:
      console.error(`API error: ${error.code} — ${error.message}`);
  }
}