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