Skip to main content

Error Response Format

KillB returns standardized error responses:
{
  "errorCode": "USER.0001",
  "message": ["User not found"],
  "statusCode": "404",
  "arguments": [
    {
      "key": "userId",
      "value": "invalid-id"
    }
  ]
}

HTTP Status Codes

StatusMeaningAction
200SuccessProcess response
201CreatedResource created successfully
400Bad RequestFix request parameters
401UnauthorizedRefresh token
403ForbiddenCheck permissions
404Not FoundResource doesn’t exist
409ConflictResource already exists
429Too Many RequestsImplement backoff
500Server ErrorRetry with backoff

Common Error Codes

Authentication Errors

CodeMessageSolution
AUTH.0001Invalid credentialsCheck email/password
AUTH.0002Token expiredRefresh access token
AUTH.0003Invalid tokenRe-authenticate

User Errors

CodeMessageSolution
USER.0001User not foundVerify user ID
USER.0002Invalid documentCheck document format
USER.0003Email already existsUse different email
USER.0004Underage userUser must be 18+

Account Errors

CodeMessageSolution
ACCOUNT.0001Account not foundVerify account ID
ACCOUNT.0002Invalid bank codeCheck supported banks
ACCOUNT.0003Invalid wallet addressValidate address format

Ramp Errors

CodeMessageSolution
RAMP.0001Quotation expiredCreate new quotation
RAMP.0002Insufficient balanceCheck pre-fund balance
RAMP.0003User limit exceededUpgrade KYC level
RAMP.0004Invalid accountVerify account status

Error Handling Strategy

class KillBAPIError extends Error {
  constructor(response) {
    super(response.message.join(', '));
    this.errorCode = response.errorCode;
    this.statusCode = response.statusCode;
    this.arguments = response.arguments;
  }
}

const makeAPIRequest = async (endpoint, options) => {
  try {
    const response = await fetch(endpoint, options);
    
    if (!response.ok) {
      const error = await response.json();
      throw new KillBAPIError(error);
    }
    
    return await response.json();
    
  } catch (error) {
    if (error instanceof KillBAPIError) {
      // Handle API errors
      console.error(`API Error ${error.errorCode}:`, error.message);
      
      if (error.statusCode === '401') {
        // Token expired, refresh
        await refreshToken();
        return makeAPIRequest(endpoint, options);
      }
      
      if (error.errorCode === 'RAMP.0001') {
        // Quotation expired, get new one
        const newQuote = await getNewQuotation();
        // Retry with new quote
      }
    }
    
    throw error;
  }
};

Retry Logic

Implement exponential backoff:
const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // Don't retry client errors (4xx)
      if (error.statusCode && error.statusCode < 500) {
        throw error;
      }
      
      // Exponential backoff
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};

// Usage
const user = await retryWithBackoff(() => createUser(userData));

User-Friendly Messages

Map technical errors to user messages:
const getUserMessage = (error) => {
  const messages = {
    'AUTH.0002': 'Your session expired. Please log in again.',
    'USER.0003': 'This email is already registered.',
    'RAMP.0001': 'The price quote expired. Please try again.',
    'RAMP.0003': 'Transaction amount exceeds your limit. Please verify your identity to increase limits.'
  };
  
  return messages[error.errorCode] || 'An error occurred. Please try again.';
};

Next Steps