SDK
Error Handling
Handle API errors gracefully in your application.
All API errors are thrown as ORPCError instances with a machine-readable code and a human-readable message.
Catching errors
import { ORPCError } from "@orpc/client";
try {
await connect.contact.get({ id: "nonexistent" });
} catch (error) {
if (error instanceof ORPCError) {
console.error(error.code); // "NOT_FOUND"
console.error(error.message); // "Contact not found"
}
}Error codes
| Code | HTTP Status | Meaning |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid API key |
FORBIDDEN | 403 | Key doesn't have access to this organization |
BAD_REQUEST | 400 | Invalid input (check the message for details) |
NOT_FOUND | 404 | Resource doesn't exist |
CONFLICT | 409 | Resource already exists (e.g. duplicate contact) |
TOO_MANY_REQUESTS | 429 | Rate limit exceeded — back off and retry |
INTERNAL_SERVER_ERROR | 500 | Something went wrong on our end |
Retry strategy
For 429 and 5xx errors, implement exponential backoff:
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
return await fn();
} catch (error) {
if (
error instanceof ORPCError &&
(error.code === "TOO_MANY_REQUESTS" ||
error.code === "INTERNAL_SERVER_ERROR") &&
attempt < maxRetries
) {
await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
continue;
}
throw error;
}
}
throw new Error("Unreachable");
}
// Usage
const contact = await withRetry(() => connect.contact.get({ id: "ct_..." }));