Request And Response

Overview

The API returns data in JSON format. Each successful request will return a status of "success". example response

{
  "id": "8212bab8-5911-48a0-b177-24923ef2329a",
  "trackTitle": "Wicked Games",
  "artists": [
    {
      "id": "9451b6b2-8746-4d43-abd7-c355ed1e3048",
      "name": "The Weeknd",
      "href": "https://open.spotify.com/artist/1Xyo4u8uXC1ZmMpatF05PJ"
    }
  ],
  "durationMs": 325305,
  "isrc": "USUM72104140",
  "ean": null,
  "upc": null,
  "href": "https://open.spotify.com/track/00aqkszH1FdUiJJWvX6iEl",
  "availableCountries": "AR,AU,AT,BE,BO,BR,BG,CA,CL,CO,CR,CY,CZ,DK,DO,DE,EC,EE,SV,FI,FR,GR,GT,HN,HK,HU,IS,IE,IT,LV,LT,LU,MY,MT,MX,NL,NZ,NI,NO,PA,PY,PE,PH,PL,PT,SG,SK,ES,SE,CH,TW,TR,UY,US,GB,AD,LI,MC,ID,JP,TH,VN,RO,IL,ZA,SA,AE,BH,QA,OM,KW,EG,MA,DZ,TN,LB,JO,PS,IN,BY,KZ,MD,UA,AL,BA,HR,ME,MK,RS,SI,KR,BD,PK,LK,GH,KE,NG,TZ,UG,AG,AM,BS,BB,BZ,BT,BW,BF,CV,CW,DM,FJ,GM,GE,GD,GW,GY,HT,JM,KI,LS,LR,MW,MV,ML,MH,FM,NA,NR,NE,PW,PG,WS,SM,ST,SN,SC,SL,SB,KN,LC,VC,SR,TL,TO,TT,TV,VU,AZ,BN,BI,KH,CM,TD,KM,GQ,SZ,GA,GN,KG,LA,MO,MR,MN,NP,RW,TG,UZ,ZW,BJ,MG,MU,MZ,AO,CI,DJ,ZM,CD,CG,IQ,LY,TJ,VE,ET,XK",
  "popularity": 69
}

Array Query Parameters

Our API supports two ways to pass arrays in query parameters:

1. Repeated Query Parameters

GET /track?ids=1&ids=2&ids=3...

Example:

https://api.reccobeats.com/v1/track?ids=01K4zKU104LyJ8gMb7227B&ids=0108kcWLnn2HlH2kedi1gn&ids=012gXGNwfkqsXBIhEpE0kl

2. Comma-Separated Values (CSV)

GET /track?ids=1,2,3...

Example:

https://api.reccobeats.com/v1/track?ids=01K4zKU104LyJ8gMb7227B,0108kcWLnn2HlH2kedi1gn,012gXGNwfkqsXBIhEpE0kl

HTTP Status & Error Code

HTTP Status Code

The ReccoBeats API uses standard HTTP status codes to indicate the status of your request:

• 200 OK: The request was successful.
• 400 Bad Request: The request was malformed or contains invalid parameters.
• 403 Forbidden: The API key doesn’t have permissions to perform the request.
• 429 Too Many Requests: You have exceeded the rate limit for requests.
• 500 Internal Server Error: An unexpected error occurred on the server.

Error Code

Code	Exception	Info
4001	MissingServletRequestParameterException	The request was missing required parameters.
4002	BadRequestException	The request was malformed or contains invalid parameters.
4003	DateTimeParseException	The request contains invalid datetime format.
4004	ConstraintViolationException	Validation exception for parameters value.
4041	ResourceNotFoundException	Cannot find the entity given ID in the request.
4042	NoResourceFoundException	URL path is incorrect or not exist.
4291	TooManyRequestException	You have exceeded the rate limit for requests.
4032	AccessDeniedException	Account not exist.
4031	InactiveAccountException	Account is inactive.
4011	PasswordIncorrect	Incorrect username or password.
5001	UnknownException	Unknown internal server error.

Error Handle

Common Error Response:

{
  "timestamp": "2025-01-12T07:09:10.228+00:00",
  "error": "Size must be a greater than zero",
  "path": "uri=/v1/track/recommendation",
  "status": 4002
}

Attributes

timestamp required

The time when the error occurred.

error required

A message describing the error.

path required

The URL path where the error occurred.

status required

A unique code identifying the error.

Validation Error Response

{
  "status": 4004,
  "errors": [
    {
      "path": "getRecommendation.size",
      "message": "must be less than or equal to 100"
    }
  ]
}

Attributes

status required

A unique code identifying the error.

info

Validation error code is always 4004

errors required

List of validation errors

errors[].path required

Name of invalid parameter

errors[].message required

Error message detail