Error Catalog - BeatPass Developer Docs

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.

Account disabled

403 Account has been suspended.Resolution: Contact contact@beatpass.ca for assistance.

Email not verified

403 Email verification is pending.Resolution: Check your inbox for the verification link. Request a new one if needed.

Token expired

401 Your authentication token has expired.Resolution: Generate a new token from Account Settings → Developers.

Unauthenticated

401 No valid authentication token found.Resolution: Include a valid Bearer token in your request. Contact support if your token has expired.

Track & Upload Errors

Upload Validation
Processing
Access

File too large

422 File exceeds maximum size (256 MB).Resolution: Compress or reduce file size before uploading.

Invalid file format

422 Unsupported audio format.Resolution: Use WAV, FLAC, or AIFF. MP3 files are not accepted.

Duration issues

422 Track duration must be at least 1 second.Resolution: Ensure the uploaded file has a valid duration.

Missing required fields

422 Title, BPM, or Genre not provided.Resolution: Fill in all required metadata fields.

Purchase & Licensing Errors

Purchase Flow

Error	Code	Cause	Resolution
`Track not for sale`	400	No license configured	Contact producer
`Already purchased`	409	User already owns license	Check purchases
`Exclusive already sold`	410	Exclusive no longer available	Track sold exclusively
`Price changed`	409	Price updated since page load	Refresh and retry
`Checkout expired`	400	Took too long to complete	Start new checkout

Payment Errors

Error	Code	Cause	Resolution
`Payment failed`	402	Card declined	Try different payment method
`Card declined`	402	Issuer declined transaction	Contact card issuer
`Insufficient funds`	402	Not enough balance	Use different card
`Invalid card`	422	Card number invalid	Check card details
`Expired card`	422	Card past expiration	Update card info
`Processing error`	500	Stripe communication issue	Retry in a moment

License Errors

Error	Code	Cause	Resolution
`License not found`	404	Invalid license ID	Verify license ID
`License revoked`	410	License was revoked	Contact support
`Download expired`	403	Download link timed out	Get new download link

Beat Request Errors

Creation

Error	Code	Cause	Resolution
`No tokens remaining`	429	Monthly token allowance exhausted	Wait for monthly reset or upgrade
`Insufficient tokens`	429	Not enough tokens for chosen duration	Choose a shorter duration or wait
`Description too short`	422	Under minimum length (10 characters)	Add more detail
`Reference track required`	422	Missing reference track URL	Provide a valid URL
`Invalid reference track`	422	URL format invalid	Provide a valid YouTube, Spotify, or SoundCloud link

Submission

Error	Code	Cause	Resolution
`Request not found`	404	Invalid request ID	Verify ID
`Request expired`	410	Duration window (24/48/72h) has closed	Find an active request
`Duplicate submission`	409	Same track already submitted	Choose a different track
`Submission limit reached`	422	Producer already submitted 5 tracks	Maximum tracks per request reached
`Duplicate audio detected`	409	Audio fingerprint matches existing submission	Try a different track
`Track not platform-hosted`	422	Track is an external link, not uploaded	Upload the track to the platform first
`Fingerprint not completed`	422	Track hasn’t finished audio processing	Wait for processing to complete
`Not track owner`	403	Producer doesn’t own or collaborate on track	Submit only your own tracks
`Self-submission blocked`	403	Cannot submit to your own request	Find another user’s request

Deletion & Renewal

Error	Code	Cause	Resolution
`Not request owner`	403	Only the creator can delete or renew	Verify ownership
`Request still active`	409	Cannot renew a request that hasn’t expired	Wait for expiration or delete
`Renewal window expired`	410	Request expired more than 30 days ago	Create a new request instead
`No token for renewal`	429	No tokens available to renew	Wait for monthly reset or upgrade

Producer Program Request Errors

These errors apply to Backstage request creation and submission eligibility checks.

Error	Code	Cause	Resolution
`Unauthenticated`	401	Missing or invalid auth token	Authenticate with a valid Bearer token
`Forbidden`	403	Missing `backstageRequests.create` permission	Grant/create permission for the user
`backstage_request_pending`	409	User already has a pending request	Wait for the pending request decision before submitting again
`backstage_request_revoked`	409	User has a revoked request in history	Direct the user to the contact page (`/contact`) to appeal

Backstage create submissions are blocked globally per user when a pending or revoked request exists, regardless of request type (become-artist, verify-artist, or claim-artist). If both statuses exist, pending takes precedence.

Audio Recon Errors

Error	Code	Cause	Resolution
`Unauthorized`	401	No valid authentication token	Include a Bearer token in your request
`Forbidden`	403	You are not a credited producer on this track	Only credited producers and admins can view Audio Recon matches
`Not Found`	404	Track does not exist	Verify the track ID is correct

Audio Recon matches are only available for tracks with a verified artist profile. If the track’s primary artist is not verified, the response will return an empty matches array with artist_verified: false.

Messaging Errors

Sending Messages

Error	Code	Cause	Resolution
`Recipient not found`	404	Invalid user ID	Verify recipient
`User blocked you`	403	Recipient blocked sender	Cannot message this user
`You blocked user`	403	Sender blocked recipient	Unblock to message
`Message too long`	422	Message exceeds limit	Shorten message
`Rate limited`	429	Too many messages	Wait before sending more

Conversation

Error	Code	Cause	Resolution
`Conversation not found`	404	Invalid conversation ID	Verify ID
`Not a participant`	403	User not in conversation	Cannot access

Collection & Library Errors

Saves & Playlists

Error	Code	Cause	Resolution
`Library full`	429	Maximum saved items reached	Remove old items
`Playlist full`	429	Maximum tracks per playlist	Create new playlist
`Playlist limit reached`	429	Maximum playlists reached	Delete unused playlists
`Track already saved`	409	Already in library	No action needed
`Track already in playlist`	409	Duplicate in playlist	Track exists

Collaborative Playlists

Error	Code	Cause	Resolution
`Max editors reached`	429	Maximum collaborators	Remove editor first
`Invitation expired`	410	Invitation expired	Send new invitation
`Already invited`	409	Pending invitation exists	Wait for response
`Cannot re-invite yet`	429	Cooldown period active	Wait to re-invite

Following

Error	Code	Cause	Resolution
`Already following`	409	Already followed	No action needed
`Not following`	404	Cannot unfollow if not following	Check following status
`Follow limit reached`	429	Maximum following reached	Unfollow some accounts
`Follow rate limited`	429	Too many follows	Wait before following more

Reposts

Error	Code	Cause	Resolution
`Already reposted`	409	Track already reposted	No action needed
`Repost limit reached`	429	Repost limit exceeded	Wait for limit reset
`Cannot repost own track`	400	Self-repost not allowed	N/A

Radio Errors

Error	Code	Cause	Resolution
`Skip limit reached`	429	Skip limit exceeded	Wait for reset
`Station not found`	404	Invalid station	Choose valid station
`Concurrent stream limit`	429	Already streaming elsewhere	Stop other stream

Rate Limiting

Rate Limit Response

{
  "message": "Too Many Attempts.",
  "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 - Service Unavailable

503 Platform is undergoing maintenance.Resolution: Check the status page for updates.

504 - Gateway Timeout

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

Check Error Message

Read the message field for human-readable explanation.

Check Validation Errors

Review errors object for field-specific issues.

Verify Authentication

Ensure your Bearer token is valid and included in the Authorization header.

Check Rate Limits

Review X-RateLimit-* headers.

Retry with Backoff

For transient errors, wait and retry.

Contact Support

For persistent issues, provide error details and timestamps.

API Overview

API fundamentals.

Rate Limits

Throttling details.

Introduction

Core Concepts

API Reference

Search

Playlists

Artists

Albums

Tracks

Tags

Genres

Users

Auth

License Certificates

Audio Fingerprinting

Playlist Collaboration

Reposts

Track Plays

Radio

Cover Art

Track Purchases

Beat Requests

Producer Intelligence

User Library

Leaderboards

Messaging

Collections

Stripe Connect

Exclusive Licenses

Coupons

​Overview

​Error Response Format

​HTTP Status Codes

400

401

403

404

409

422

429

500

​Authentication Errors

​Track & Upload Errors

​Purchase & Licensing Errors

​Purchase Flow

​Payment Errors

​License Errors

​Beat Request Errors

​Creation

​Submission

​Deletion & Renewal

​Producer Program Request Errors

​Audio Recon Errors

​Messaging Errors

​Sending Messages

​Conversation

​Collection & Library Errors

​Saves & Playlists

​Collaborative Playlists

​Social & Following Errors

​Following

​Reposts

​Radio Errors

​Rate Limiting

​Rate Limit Response

​Rate Limit Headers

​Handling Rate Limits

Exponential Backoff

Check Headers

Queue Requests

Cache Responses

​Server Errors (5xx)

​Troubleshooting Checklist

​Related Resources

API Overview

Rate Limits

Overview

Error Response Format

HTTP Status Codes

Authentication Errors

Track & Upload Errors

Purchase & Licensing Errors

Purchase Flow

Payment Errors

License Errors

Beat Request Errors

Creation

Submission

Deletion & Renewal

Producer Program Request Errors

Audio Recon Errors

Messaging Errors

Sending Messages

Conversation

Collection & Library Errors

Saves & Playlists

Collaborative Playlists

Social & Following Errors

Following

Reposts

Radio Errors

Rate Limiting

Rate Limit Response

Rate Limit Headers

Handling Rate Limits

Server Errors (5xx)

Troubleshooting Checklist

Related Resources