Error Handling in SDKs

{
  ok: boolean;            // false when the request failed
  code?: number;          // HTTP status code (e.g. 401, 429)
  error?: {
    errorCode: string;        // Descope error code, e.g. "E061102"
    errorDescription: string; // human-readable summary
    errorMessage?: string;    // extra context (not always present)
  };
  data?: T;               // present when ok === true
}

import DescopeClient from '@descope/node-sdk';
const descopeClient = DescopeClient({ projectId: '__ProjectID__' });
const { DescopeErrors } = DescopeClient;

const resp = await descopeClient.otp.verify.email(loginId, code);
if (!resp.ok) {
  // Read the code + description off the response
  console.log(resp.error?.errorCode);         // "E061103"
  console.log(resp.error?.errorDescription);
  console.log(resp.code);                      // HTTP status, e.g. 401

  // Check for a specific typed error code
  if (resp.error?.errorCode === DescopeErrors.tooManyOTPAttempts) {
    // too many wrong OTP attempts (E061103)
  }

  // Check for a category using the HTTP status code
  if (resp.code === 429) {
    // rate limited
  }
} else {
  // Success — use resp.data
  const { sessionJwt } = resp.data;
}

class AuthException(Exception):
    status_code: int | None    # HTTP status code (e.g. 400, 401, 500)
    error_type: str | None     # always "server error" for failed requests
    error_message: str | None  # the raw response body for failed requests

class RateLimitException(Exception):
    status_code: str | None       # Descope code string, e.g. "E130429" — not the HTTP int used on AuthException
    error_type: str | None        # always "API rate limit exceeded"
    error_description: str | None # from the errorDescription JSON field
    error_message: str | None     # from the errorMessage JSON field
    rate_limit_parameters: dict   # {"Retry-After": <seconds as int>}

import json
from descope import (
    API_RATE_LIMIT_RETRY_AFTER_HEADER,
    AuthException,
    DeliveryMethod,
    DescopeClient,
    RateLimitException,
)

descope_client = DescopeClient(project_id="__ProjectID__")

try:
    jwt_response = descope_client.otp.verify_code(
        DeliveryMethod.EMAIL, login_id, code
    )
    session_token = jwt_response["sessionToken"].get("jwt")

# RateLimitException is a separate type and is not caught by AuthException
except RateLimitException as e:
    retry_after = e.rate_limit_parameters.get(API_RATE_LIMIT_RETRY_AFTER_HEADER, 0)
    # e.status_code holds the Descope code, e.g. "E130429" — not 429

except AuthException as e:
    # Read the HTTP status code off the exception
    if e.status_code == 401:
        # unauthorized
        pass

    # Check for a specific error code by parsing the raw body
    try:
        body = json.loads(e.error_message)
    except (TypeError, ValueError):
        body = {}

    if body.get("errorCode") == "E061103":
        # too many wrong OTP attempts
        pass

type Error struct {
    Code        string         // e.g. "E061102"
    Description string         // human-readable summary
    Message     string         // extra context (not always present)
    Info        map[string]any // extra metadata (HTTP status, Retry-After)
}

result, err := descopeClient.Auth.OTP().VerifyCode(ctx, descope.MethodEmail, loginID, code, w)

// 1. Check for a specific error code
if descope.IsError(err, "E061102") {
    // wrong OTP code
}

// 2. Or match a predefined error with the standard errors.Is (requires: import "errors")
if errors.Is(err, descope.ErrInvalidOneTimeCode) {
    // wrong OTP code (E061102)
}

// 3. Check for a category (400 / 401 / 403 / 404)
if descope.IsUnauthorizedError(err) {
    // unauthorized
}

// 4. Read the code and description directly
if de := descope.AsError(err); de != nil {
    log.Printf("failed: [%s] %s", de.Code, de.Description)
}

if de := descope.AsError(err, descope.ErrRateLimitExceeded.Code); de != nil {
    retryAfter := de.Info[descope.ErrorInfoKeys.RateLimitExceededRetryAfter] // seconds
}

import com.descope.client.Config;
import com.descope.client.DescopeClient;
import com.descope.enums.DeliveryMethod;
import com.descope.exception.ClientFunctionalException;
import com.descope.exception.DescopeException;
import com.descope.exception.ErrorCode;
import com.descope.exception.RateLimitExceededException;
import com.descope.exception.ServerCommonException;
import com.descope.model.auth.AuthenticationInfo;
import com.descope.sdk.auth.OTPService;

DescopeClient descopeClient = new DescopeClient(
    Config.builder().projectId("__ProjectID__").build());
OTPService otps = descopeClient.getAuthenticationServices().getOTPService();

try {
    AuthenticationInfo info = otps.verifyCode(DeliveryMethod.EMAIL, loginId, code);
}
// 1. Rate limits carry the number of seconds to wait
catch (RateLimitExceededException e) {
    long waitSeconds = e.getRetryAfterSeconds();
}
// 2. Local token validation failed, e.g. code "G030002"
catch (ClientFunctionalException e) {
    System.err.printf("%s - %s%n", e.getCode(), e.getMessage());
}
// 3. API and argument errors
catch (ServerCommonException e) {
    // Check for a specific error code
    if (ErrorCode.INVALID_ARGUMENT.equals(e.getCode())) {
        // invalid argument (E011004)
    }
    if ("E061103".equals(e.getCode())) {
        // too many wrong OTP attempts
    }
    String rawBody = e.getServerResponse();
}
// 4. Or catch the base type and read code + message off any of them
catch (DescopeException e) {
    System.err.printf("%s - %s%n", e.getCode(), e.getMessage());
}

Descope::Exception          # base class, exposes #error_data
├── Descope::AuthException      # raised by local validation, before any request
├── Descope::ArgumentException  # raised by local validation, before any request
└── Descope::HTTPError          # raised from an HTTP response; adds #http_code and #headers
    ├── Descope::BadRequest        # 400
    ├── Descope::Unauthorized      # 401
    ├── Descope::AccessDenied      # 403
    ├── Descope::NotFound          # 404
    ├── Descope::MethodNotAllowed  # 405
    ├── Descope::RateLimitException # 429
    ├── Descope::ServerError       # 500
    ├── Descope::Unsupported       # any other status
    └── Descope::RequestTimeout    # the request timed out

require 'descope'
require 'json'

descope_client = Descope::Client.new(project_id: '__ProjectID__')

begin
  jwt_response = descope_client.otp_verify_code(
    method: Descope::Mixins::Common::DeliveryMethod::EMAIL,
    login_id: 'user@example.com',
    code: '123456'
  )

# 1. Check for a category by rescuing the matching class
rescue Descope::RateLimitException => e
  # rate limited (429); the SDK already retried this a few times
  puts "Rate limited, headers: #{e.headers}"

rescue Descope::HTTPError => e
  # 2. Read the HTTP status off the error
  puts "API error (#{e.http_code})"

  # 3. Check for a specific error code by parsing the raw body
  body = begin
    JSON.parse(e.message)
  rescue JSON::ParserError
    {}
  end

  puts body['errorCode']         # e.g. "E061103"
  puts body['errorDescription']

rescue Descope::Exception => e
  # 4. Local validation failed before the request was sent
  puts "Validation error: #{e.message} (#{e.error_data[:code]})"
end

{
  "statusCode": 400,
  "errorType": "E061102",
  "errorMessage": "One time code is invalid"
}

use Descope\SDK\DescopeSDK;
use Descope\SDK\Exception\AuthException;
use Descope\SDK\Exception\RateLimitException;
use Descope\SDK\Exception\TokenException;
use Descope\SDK\Exception\ValidationException;

$descopeSDK = new DescopeSDK([
    'projectId' => $_ENV['DESCOPE_PROJECT_ID'],
]);

try {
    $response = $descopeSDK->otp->verifyCode('email', 'user@example.com', '123456');
}
// 1. Rate limited (429)
catch (RateLimitException $e) {
    // No Retry-After value is parsed; back off on your own schedule
}
catch (AuthException $e) {
    // 2. Read the description off the exception
    echo $e->getMessage();

    // 3. Check for a specific error code, which lives in "errorType"
    $details = json_decode((string) $e, true);
    if (($details['errorType'] ?? null) === 'E061103') {
        // too many wrong OTP attempts
    }

    // 4. Check for a category using the HTTP status code
    if (($details['statusCode'] ?? null) === 401) {
        // unauthorized
    }

    // The underlying Guzzle exception is available for logging
    $guzzleException = $e->getPrevious();
}
catch (ValidationException $e) {
    // A required argument was empty, e.g. a missing session token
}
catch (TokenException $e) {
    // Local JWT validation failed, e.g. "Invalid signature"
}

public class DescopeException : ApplicationException
{
    public string? ErrorCode { get; }        // "E062504"
    public string? ErrorDescription { get; } // "Token expired"
    public string? ErrorMessage { get; }     // "Failed to load magic link token"
    // Message => "[E062504]: Token expired (Failed to load magic link token)"
}

using Descope;

try
{
    var response = await client.Auth.V1.Auth.Magiclink.Verify.PostAsync(
        new VerifyMagicLinkRequest { Token = token });
}
catch (DescopeException e)
{
    // Read the details off the exception
    Console.WriteLine(e.ErrorCode);        // "E062504"
    Console.WriteLine(e.ErrorDescription); // "Token expired"
    Console.WriteLine(e.Message);          // "[E062504]: Token expired (Failed to load magic link token)"

    // Check for a specific error code
    if (e.ErrorCode == "E061103")
    {
        // too many wrong OTP attempts
    }

    // Unparseable body: SDK substitutes HTTP<status>, e.g. "HTTP401"
    if (e.ErrorCode == "HTTP401")
    {
        // unauthorized (server returned 401 with no parseable error body)
    }
}