A1D - Picadabra Docs

The Picadabra API uses standard oRPC error codes. All errors include a code and message.

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication token
`FORBIDDEN`	403	Authenticated but not authorized for this action
`NOT_FOUND`	404	Requested resource does not exist
`PAYLOAD_TOO_LARGE`	413	Request body exceeds size limit
`INTERNAL_SERVER_ERROR`	500	Server-side error

Handling Errors

try {
	const  = await ..()
} catch () {
	if ( instanceof ) {
		// Check error code
		const  = ( as any).code

		switch () {
			case 'UNAUTHORIZED':
				.('Please log in')
				break
			case 'FORBIDDEN':
				.('Access denied')
				break
			case 'NOT_FOUND':
				.('Resource not found')
				break
			default:
				.('Error:', .)
		}
	}
}

Error Response Structure

type  = {
	: string
	: string
	?: unknown
}

Common Error Scenarios

Authentication Errors

// No auth token provided
const  = ({
	: 'https://api.picadabra.example.com',
	// getAuthToken not provided
})

// This will throw UNAUTHORIZED
try {
	await ..()
} catch () {
	// code: 'UNAUTHORIZED'
}

Resource Not Found

try {
	await ..({ : 'non-existent-file.txt' })
} catch () {
	// code: 'NOT_FOUND'
}

Rate Limiting

The API enforces rate limits (100 requests per 60 seconds per IP). Exceeding this limit returns a 429 Too Many Requests response.

async function <>(: () => <>,  = 3): <> {
	for (let  = 0;  < ; ++) {
		try {
			return await ()
		} catch () {
			const  = ( as any).status
			if ( === 429 &&  <  - 1) {
				// Exponential backoff
				await new (() => (, .(2, ) * 1000))
				continue
			}
			throw 
		}
	}
	throw new ('Max retries exceeded')
}

// Usage
const  = await (() => ..())

How is this guide?

Errors