Skip to main content

​
Understanding error responses

The Username API uses the RFC 7807 Problem Details format for all error responses. This standardized format makes it easy to handle errors programmatically and provides clear, actionable error messages.

​
Error response structure

All error responses follow this structure:
​
type
string
required
A URI reference that identifies the problem type. This URI points to documentation explaining the error.
​
title
string
required
A short, human-readable summary of the problem type.
​
status
integer
required
The HTTP status code for this occurrence of the problem (e.g., 400, 401, 429).
​
detail
string
required
A human-readable explanation specific to this occurrence of the problem.
​
instance
string
required
A URI reference that identifies the specific occurrence of the problem (usually the endpoint path).
​
retryAfter
integer
Number of seconds to wait before retrying the request. Only included in 429 (Rate Limit Exceeded) responses.

​
Handling errors programmatically

All errors return a JSON response with the Problem Details format. You can handle errors by checking the HTTP status code and parsing the error response: 
try {
  const response = await fetch('https://api.username.dev/check?input=test', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  
  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${error.status}: ${error.title}`);
    console.error(error.detail);
    
    // Handle specific error types
    if (error.status === 429 && error.retryAfter) {
      // Implement exponential backoff
      await new Promise(resolve => setTimeout(resolve, error.retryAfter * 1000));
      // Retry request
    }
  } else {
    const data = await response.json();
    // Process successful response
  }
} catch (error) {
  console.error('Network error:', error);
}

​
Error code reference

For detailed information about each error code, see: