Documenting API errors

[monolithed]

Could you please add detailed information to the API documentation about all possible errors, their meanings, and how to handle them? At the moment, understanding the differences between invalid_jwt, invalid_session_cookie, and no_session_cookie_provided requires digging into the code. Additionally, some errors, like invalid_grant, seem to come from external sources and aren't documented in the codebase.

Current:

export declare class GenericServerException extends Error implements RequestException {
    readonly status: number;
    readonly rawData: unknown;
    readonly requestID: string;
    readonly name: string;
    readonly message: string;
    constructor(status: number, message: string | undefined, rawData: unknown, requestID: string);
}

Expected:

type Organization = {
    id: string;
    name: string;
};


type Code = 'organization_selection_required' | 'no_session_cookie_provided' ...

type User = {
    object: string;
    id: string;
    email: string;
    email_verified: boolean;
    first_name: string | null;
    last_name: string | null;
    profile_picture_url: string | null;
    last_sign_in_at: string;
    created_at: string;
    updated_at: string;
    external_id: string | null;
};

type RawData = {
    code: Code;
    message: string;
    pending_authentication_token: string;
    user: User;
    organizations: Organization[];
};

type GenericServerException = {
    status: number;
    rawData: RawData;
    requestID: string;
    name: string;
    message: string;
};

[kevinmitch14]

It would be nice to know if GenericServerException, OauthException etc. can be 'leaked' to the client

[monolithed]

@kevinmitch14, they can https://github.com/workos/workos-node/issues/1202 🙂

[kevinmitch14]

I mean is it safe to expose these on the client!