Error Catalog

Common API error codes, messages, and suggested resolutions across BeatPass features.

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 [e-mail] 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

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.

Processing

Transcode failed

500 Audio processing encountered an error.

Resolution: Re-export from your DAW and upload again.

Fingerprint collision

409 Duplicate audio detected.

Resolution: This track may already exist on the platform.

Processing timeout

504 File took too long to process.

Resolution: Try a smaller file or retry later.

Access

Track not found

404 Track ID doesn’t exist or was deleted.

Resolution: Verify the track ID is correct.

Track unavailable

410 Removed by owner or moderation.

Resolution: This track is no longer accessible.

Private track

403 Track is not published.

Resolution: Only the owner can access unpublished tracks.

---

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

---

Social & Following Errors

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

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 your Bearer token is valid and included in the Authorization header.

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.

---

Related Resources

API Overview

API fundamentals.

Rate Limits

Throttling details.