Error Codes

Cito API uses conventional HTTP response codes to indicate success or failure of requests.

HTTP Status Codes

Code	Error	Description
`400`	Bad Request	Invalid parameters or malformed request
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	API key doesn't have access to this resource
`404`	Not Found	Resource doesn't exist
`429`	Rate Limit	Too many requests, see rate limits
`500`	Server Error	Something went wrong on our end
`503`	Service Unavailable	API is temporarily down (check status page)

Error Response Format

All errors follow the same structure:

{
  "error": {
    "type": "invalid_request",
    "message": "Player 'Bugha123' not found",
    "param": "username",
    "code": "player_not_found"
  }
}

Field	Description
`type`	The type of error (see table below)
`message`	A human-readable error message
`param`	The parameter that caused the error (if applicable)
`code`	A machine-readable error code

Error Types

Type	Description
`invalid_request`	The request was invalid or malformed
`authentication_error`	Invalid or expired API key
`authorization_error`	API key lacks permission for this action
`not_found`	The requested resource was not found
`rate_limit_exceeded`	Too many requests in the time window
`validation_error`	One or more request parameters are invalid
`internal_error`	An unexpected error occurred on our servers

Handling Errors

try {
  const response = await fetch('https://api.citoapi.com/v1/fortnite/players/Bugha', {
    headers: { 'Authorization': 'Bearer sk_live_...' }
  });

  if (!response.ok) {
    const { error } = await response.json();

    switch (error.type) {
      case 'not_found':
        console.log(`Player not found: ${error.message}`);
        break;
      case 'rate_limit_exceeded':
        // Wait and retry
        await sleep(error.retry_after * 1000);
        break;
      case 'authentication_error':
        console.log('Invalid API key');
        break;
      default:
        console.log(`Error: ${error.message}`);
    }
    return;
  }

  const data = await response.json();
  console.log(data);
} catch (err) {
  console.error('Network error:', err);
}

Common Issues

"Invalid API key provided"

Check that you're using the correct key prefix (sk_live_ or sk_test_) and that the key hasn't been revoked.

"Player not found"

Usernames are case-sensitive. Make sure you're using the exact username as it appears in-game.

"Rate limit exceeded"

Wait for the retry_after period and consider implementing caching or upgrading your plan.