Errors
Inspect Carpo API, transfer, and authentication errors.
Carpo API errors
The Database, Functions JSON, and Storage clients throw CarpoApiError for API failures:
try {
await carpo.database.from<Todo>('todos').select()
} catch (error) {
if (error instanceof CarpoApiError) {
console.error(error.status, error.code, error.details)
if (error.retryAfterSeconds) {
console.log(`Retry in ${error.retryAfterSeconds} seconds`)
}
}
}The error has status, optional code, optional details, and optional retryAfterSeconds fields. A network or token provider failure has status 0. Network failures use code NETWORK_ERROR; token getter failures use ACCESS_TOKEN_ERROR.
functions.invoke() returns an HTTP Response and does not throw for a non successful status. functions.invokeJson() parses JSON and throws CarpoApiError when the status is not successful.
Storage transfer errors
CarpoStorageTransferError represents a signed URL transfer failure. Its status is the HTTP status when available, otherwise null.
CarpoStorageUploadError extends it and includes intentId and idempotencyKey so the caller can inspect or resume the upload. If the byte transfer is cancelled with an AbortSignal after the intent exists, the error name is AbortError and the intent remains available until it expires or is explicitly aborted. A cancellation before intent creation has no intent to resume.
An HTTP error may not include readable details when a signed R2 URL has expired, because the browser's CORS rules can hide the response. Verify the bucket CORS configuration and retry with the same upload idempotency key when appropriate.
Auth errors
Auth methods return Better Auth's native result shape. Check the returned error value for Auth operations. These errors do not use CarpoApiError unless the failure occurred in one of the SDK's separate Carpo API clients.