Skip to main content

​
Overview

This catalog documents common errors you may encounter across BeatPass API endpoints, along with their meanings and suggested resolutions.

​
Error Response Format

All errors follow this structure: 
{
  "message": "Human-readable error description",
  "errors": {
    "field_name": ["Specific validation error"]
  }
}

​
HTTP Status Codes

400

Bad Request Malformed syntax

401

Unauthorized Auth required

403

Forbidden Not permitted

404

Not Found Doesn’t exist

409

Conflict State conflict

422

Unprocessable Validation failed

429

Too Many Rate limited

500

Server Error Internal issue

​
Authentication Errors

Invalid credentials

401 Wrong email or password combination.Resolution: Verify your credentials. Use “Forgot Password” if needed.
403 Account has been suspended.Resolution: Contact [email protected] for assistance.
403 Email verification is pending.Resolution: Check your inbox for the verification link. Request a new one if needed.
401 Your session has timed out.Resolution: Re-authenticate by logging in again.
419 Security token is missing or invalid.Resolution: Refresh the page and try again. This resets the CSRF token.
401 No valid session cookie found.Resolution: Log in to establish a session.

​
Track & Upload Errors

422 File exceeds maximum size (~250MB).Resolution: Compress or reduce file size before uploading.
422 Unsupported audio format.Resolution: Use WAV, FLAC, or AIFF. MP3 files are not accepted.
422 Track too short (<30s) or too long (>15min).Resolution: Ensure track is between 30 seconds and 15 minutes.
422 Title, BPM, or Genre not provided.Resolution: Fill in all required metadata fields.

​
Purchase & Licensing Errors

​
Purchase Flow

ErrorCodeCauseResolution
Track not for sale400No license configuredContact producer
Already purchased409User already owns licenseCheck purchases
Exclusive already sold410Exclusive no longer availableTrack sold exclusively
Price changed409Price updated since page loadRefresh and retry
Checkout session expired400Took too long to completeStart new checkout

​
Payment Errors

ErrorCodeCauseResolution
Payment failed402Card declinedTry different payment method
Card declined402Issuer declined transactionContact card issuer
Insufficient funds402Not enough balanceUse different card
Invalid card422Card number invalidCheck card details
Expired card422Card past expirationUpdate card info
Processing error500Stripe communication issueRetry in a moment

​
License Errors

ErrorCodeCauseResolution
License not found404Invalid license IDVerify license ID
License revoked410License was revokedContact support
Download expired403Download link timed outGet new download link

​
Beat Request Errors

​
Creation

ErrorCodeCauseResolution
Request limit reached429Max active requestsClose old requests first
Title is required422Missing titleProvide title
Description too short422Under minimum lengthAdd more detail

​
Response

ErrorCodeCauseResolution
Request not found404Invalid request IDVerify ID
Request closed410Request no longer accepting responsesFind open request
Already responded409User already submitted responseCannot submit twice
Request expired410Past 30-day limitRequest auto-expired

​
Status Changes

ErrorCodeCauseResolution
Cannot close403Not request ownerOnly owner can close
Already fulfilled409Request already completedNo action needed

​
Messaging Errors

​
Sending Messages

ErrorCodeCauseResolution
Recipient not found404Invalid user IDVerify recipient
User blocked you403Recipient blocked senderCannot message this user
You blocked user403Sender blocked recipientUnblock to message
Message too long422Over 5,000 charactersShorten message
Rate limited429Too many messagesWait before sending more

​
Conversation

ErrorCodeCauseResolution
Conversation not found404Invalid conversation IDVerify ID
Not a participant403User not in conversationCannot access

​
Collection & Library Errors

​
Saves & Playlists

ErrorCodeCauseResolution
Library full429Max saved items (10,000)Remove old items
Playlist full429Max tracks per playlist (500)Create new playlist
Playlist limit reached429Max playlists (100)Delete unused playlists
Track already saved409Already in libraryNo action needed
Track already in playlist409Duplicate in playlistTrack exists

​
Collaborative Playlists

ErrorCodeCauseResolution
Max editors reached42910 collaborators maxRemove editor first
Invitation expired4107-day expiry passedSend new invitation
Already invited409Pending invitation existsWait for response
Cannot re-invite yet42924-hour cooldownWait to re-invite

​
Social & Following Errors

​
Following

ErrorCodeCauseResolution
Already following409Already followedNo action needed
Not following404Cannot unfollow if not followingCheck following status
Follow limit reached429Max 5,000 followingUnfollow some accounts
Follow rate limited429Too many followsWait before following more

​
Reposts

ErrorCodeCauseResolution
Already reposted409Track already repostedNo action needed
Repost limit reached429100/day or 20/hourWait for limit reset
Cannot repost own track400Self-repost not allowedN/A

​
Radio Errors

ErrorCodeCauseResolution
Skip limit reached4296 skips/hourWait for reset
Station not found404Invalid stationChoose valid station
Concurrent stream limit429Already streaming elsewhereStop other stream

​
Rate Limiting

​
Rate Limit Response

{
  "message": "Too Many Requests",
  "retry_after": 60
}

​
Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000060
Retry-After: 60

​
Handling Rate Limits

Exponential Backoff

Wait, then double the delay on each retry attempt.

Check Headers

Monitor X-RateLimit-Remaining before making requests.

Queue Requests

Space out API calls to stay under limits.

Cache Responses

Reduce redundant calls by caching data locally.

​
Server Errors (5xx)

500 - Internal Server Error

500 An unexpected server-side issue occurred.Resolution: Retry the request. If persistent, contact support with the timestamp and endpoint.
503 Platform is undergoing maintenance.Resolution: Check the status page for updates.
504 Request took too long to process.Resolution: Retry with a smaller payload or try again later.
Server errors (5xx) are logged automatically. If you encounter persistent issues, contact support with the approximate time and endpoint details.

​
Troubleshooting Checklist

1

Check Error Message

Read the message field for human-readable explanation.
2

Check Validation Errors

Review errors object for field-specific issues.
3

Verify Authentication

Ensure session is valid and cookies are included.
4

Check Rate Limits

Review X-RateLimit-* headers.
5

Retry with Backoff

For transient errors, wait and retry.
6

Contact Support

For persistent issues, provide error details and timestamps.

API Overview

API fundamentals.

Rate Limits

Throttling details.
Last modified on December 5, 2025