Improve HTTP Error Handling with Descriptive Messages

[JorgeRosbel]

📝 Description

This PR replaces raw, generic catch-all errors with strongly-typed, descriptive HTTP error classes. Instead of logging opaque JSON or stack traces, callers can now instanceof specific errors and get:

• A clear, human‑readable message
• A status_code property for programmatic handling

Original Example from SDK Documentation

The SDK docs show the following snippet, but accessing error.status will always be undefined because caught errors are typed as unknown:

try {
  const chat = await v0.chats.create({
    message: 'Create a component',
  });
} catch (error) {
  if (error.status === 403) {
    console.error('Authentication error:', error.message);
  } else if (error.status === 429) {
    console.error('Rate limit exceeded:', error.message);
  }
}

In practice, error.status does not exist and evaluating it yields undefined.

Before

import { createClient, V0AuthError } from '@v0/sdk'

const v0 = createClient({
  apiKey: "v1:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
})


try {
  const chat = await v0.chats.create({
    message: "test",
    system: "test",
  })

  console.log(chat)
}catch(error){
  if(error instanceof V0AuthError){
    console.log(error.message);
    console.log(error.status_code)
  }
}

✨ Benefits

• Better UX: Users see clear, actionable messages instead of raw JSON.
• Simplified Debugging: Developers inspect error instanceof instead of parsing status codes.
• Performance: No round‑trip to read full response bodies for common cases.
• Maintainability: One central place defines all messages and codes.

🎯 Status Codes Covered

Code	Class	Description
400	V0BadRequestError	Invalid or malformed request
401	V0AuthError	Authentication required or session expired
402	V0PaymentRequiredError	Payment required (insufficient credits)
403	V0ForbiddenError	Permission denied or quota exceeded
404	V0NotFoundError	Resource not found
408	V0TimeoutError	Request took too long
422	V0UnprocessableEntityError	Unprocessable entity - validation failed
429	V0RateLimitError	Rate limit exceeded
500	V0InternalServerError	Server‑side error
503	V0ServiceUnavailableError	Service temporarily unavailable
504	V0GatewayTimeoutError	Gateway timeout
—	V0UnknownError	Fallback for any other status

⚠️ Development Only

Explains the purpose and usage of the createHttpError function, which is not exported in the public SDK API. It serves purely as an internal helper during development.

• Factory function that generates custom Error subclasses with:

  • A default human-readable message
  • A custom name property reflecting the error type
  • An optional status_code property for programmatic checks

Usage (development)

Internally, we use it to define all HTTP error classes:

const InternalServerError = createHttpError(
  'HTTP 500: Internal server error. Please try again later.',
  'InternalServerError',
  500
);

🎯 TypeScript Support

V0Error Union Type

For better TypeScript integration, especially with React state management, we provide a union type that includes all possible V0 errors:

import type { V0Error } from '@v0/sdk'

🧪 Testing

• Verify error messages are displayed correctly for each status code
• Ensure fallback case handles unexpected status codes
• Test that error handling doesn't break existing functionality