Errors

The TooXclusive API uses standard HTTP status codes. All error responses return a JSON body with statusCode, error, and message fields.

Error format

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or revoked API key"
}

Status codes

Code	Name	Description
200	OK	Request succeeded
400	Bad Request	Invalid parameters
401	Unauthorized	Missing or invalid API key
404	Not Found	Resource does not exist
429	Too Many Requests	Daily rate limit exceeded
500	Internal Server Error	Something went wrong on our end

401 Unauthorized

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key required. Pass it as the Authorization header: Bearer txc_live_..."
}

Causes: missing Authorization header, invalid key, revoked key.

Fix:

curl https://api.tooxclusive.com/api/v1/artists/wizkid \
  -H "Authorization: Bearer txc_live_YOUR_KEY"

429 Too Many Requests

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Daily limit of 1000 requests reached. Resets at midnight UTC."
}

Causes: exceeded your daily request limit.

Fix: wait until midnight UTC, cache responses on your end, or request a higher limit.

404 Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Artist \"unknown-artist\" not found"
}

Causes: artist or song slug doesn't exist, or a typo in the slug.

Fix — use browse or search to find the correct slug:

curl "https://api.tooxclusive.com/api/v1/artists?q=wizkid" \
  -H "Authorization: Bearer txc_live_YOUR_KEY"

curl "https://api.tooxclusive.com/api/v1/songs/search?title=essence&artistName=wizkid" \
  -H "Authorization: Bearer txc_live_YOUR_KEY"

500 Internal Server Error

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

If you see this consistently, email api@tooxclusive.com with the endpoint and parameters.

Handling errors in code

JavaScript

const response = await fetch(
  "https://api.tooxclusive.com/api/v1/artists/wizkid",
  { headers: { Authorization: "Bearer txc_live_YOUR_KEY" } },
);

if (!response.ok) {
  const error = await response.json();
  if (response.status === 429) {
    console.log("Rate limit hit — resets at midnight UTC");
  } else if (response.status === 401) {
    console.log("Invalid API key");
  } else {
    console.log("Error:", error.message);
  }
}

Python

import requests

response = requests.get(
  'https://api.tooxclusive.com/api/v1/artists/wizkid',
  headers={'Authorization': 'Bearer txc_live_YOUR_KEY'}
)

if response.status_code == 429:
  print('Rate limit hit — resets at midnight UTC')
elif response.status_code == 401:
  print('Invalid API key')
elif not response.ok:
  print('Error:', response.json()['message'])