Skip to main content

​
Error Response Format

All API errors follow a consistent JSON format: 
{
  "error": "Error Type",
  "message": "Human-readable description of what went wrong",
  "code": "SPECIFIC_ERROR_CODE",
  "details": {}
}

​
HTTP Status Codes

The Wallbit API uses standard HTTP status codes to indicate the success or failure of requests.

​
Success Codes

CodeDescription
200 OKRequest succeeded
201 CreatedResource created successfully
204 No ContentRequest succeeded, no content to return

​
Client Error Codes

CodeDescription
400 Bad RequestInvalid request parameters
401 UnauthorizedMissing or invalid API key
403 ForbiddenAPI key lacks required permissions
404 Not FoundResource doesn’t exist
422 Unprocessable EntityRequest is valid but cannot be processed
429 Too Many RequestsRate limit exceeded

​
Server Error Codes

CodeDescription
500 Internal Server ErrorSomething went wrong on our end
502 Bad GatewayUpstream service error
503 Service UnavailableAPI is temporarily unavailable

​
Common Errors

​
Authentication Errors

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY"
}
Solution: Check that you’re including the X-API-Key header with a valid API key.
{
  "error": "Forbidden",
  "message": "API key does not have permission for this operation",
  "code": "INSUFFICIENT_PERMISSIONS"
}
Solution: Create an API key with the required permissions for this endpoint.

​
Validation Errors

{
  "error": "Bad Request",
  "message": "Invalid request parameters",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "amount",
    "reason": "Must be a positive number"
  }
}
Solution: Check the details field for specific validation issues and correct your request.

​
Business Logic Errors

{
  "error": "Unprocessable Entity",
  "message": "Insufficient balance for this operation",
  "code": "INSUFFICIENT_BALANCE",
  "details": {
    "available": 100.00,
    "required": 150.00
  }
}
Solution: This indicates a business rule violation. Check the specific error code and adjust your request accordingly.

​
Error Handling Best Practices

Don’t assume requests succeed. Always check the HTTP status code before processing the response:
const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  console.error(`API Error: ${error.message} (${error.code})`);
  // Handle error appropriately
}
Log the full error response for debugging:
catch (error) {
  console.error('API Error:', {
    status: error.status,
    error: error.error,
    message: error.message,
    code: error.code,
    details: error.details
  });
}
Don’t show raw API errors to users. Map error codes to friendly messages:
const errorMessages = {
  'INSUFFICIENT_BALANCE': 'You don\'t have enough funds for this transaction.',
  'INVALID_API_KEY': 'Authentication failed. Please check your settings.',
  'RATE_LIMIT_EXCEEDED': 'Too many requests. Please try again in a moment.'
};

const userMessage = errorMessages[error.code] || 'Something went wrong. Please try again.';

​
Error Code Reference

CodeDescription
INVALID_API_KEYAPI key is missing or invalid
INSUFFICIENT_PERMISSIONSAPI key lacks required permissions
VALIDATION_ERRORRequest parameters are invalid
INSUFFICIENT_BALANCENot enough funds for the operation
ASSET_NOT_FOUNDRequested asset doesn’t exist
TRADE_FAILEDTrade could not be executed
RATE_LIMIT_EXCEEDEDToo many requests
INTERNAL_ERRORServer-side error