Robust error handling for u301: error codes, classes, HTTP status mapping, TypeScript-safe detection with isU301Error, usage examples and best practices.
Error Codes
| Error Code | Error Class | Http Status Code | Description |
|---|---|---|---|
| BAD_REQUEST | BadRequestError | 400 | The request was invalid or cannot be processed. |
| UNAUTHORIZED | UnauthorizedError | 401 | Authentication is required and has failed or has not been provided. |
| FORBIDDEN | ForbiddenError | 403 | The request is valid but the server is refusing action. |
| NOT_FOUND | NotFoundError | 404 | The requested resource could not be found. |
| VALIDATION_FAILED | ValidationError | 422 | The request was well-formed but contained invalid data. |
| RATE_LIMITED | RateLimitError | 429 | Too many requests have been made in a given amount of time. |
| NETWORK_ERROR | NetworkError | 0 | No HTTP response status code was received or could be reported for a network request |
| SERVER_ERROR | ServerError | >= 500 | The server encountered an error while processing the request. |
| UNKNOWN | Other | An unknown error occurred. |
When a matching Error Code is encountered, the u301 library throws the corresponding error class. Use isU301Error to determine whether an error originated from the u301 library. Supplying an Error Code also narrows the TypeScript type.
import { isU301Error, U301 } from 'u301'
try {
const u301 = new U301({
apiKey: '<YOUR_API_KEY>',
workspaceId: '<YOUR_WORKSPACE_ID>',
debug: true,
})
await u301.links.create('https://example.com')
} catch (error) {
if (isU301Error(error, 'RATE_LIMITED')) {
console.log('Check the quota or rate-limit details before retrying:', error.details)
}
}Monthly link quota errors
A link creation request that exceeds the workspace's monthly allowance returns HTTP 429 with API code MONTHLY_LINK_LIMIT_REACHED. Its JSON body includes limit, used, remaining, and resets_at (UTC).
The SDK still exposes this as RateLimitError with SDK code RATE_LIMITED. Read error.details to distinguish the monthly quota from a temporary request-rate limit; do not retry it continuously.
if (isU301Error(error, 'RATE_LIMITED')) {
const details = error.details as {
code?: string;
resets_at?: string;
remaining?: number;
} | undefined;
if (details?.code === 'MONTHLY_LINK_LIMIT_REACHED') {
console.log('Monthly allowance resets at:', details.resets_at);
console.log('New links still available:', details.remaining);
}
}For a monthly quota error, wait for the reset, reduce an oversized batch, or move to a plan with a larger allowance. Existing links keep working. See Monthly link allowances for existing-account protection and the full response example.
Last updated on