Skip to main content

​
Overview

The Pump.fun API uses standard HTTP status codes to indicate the success or failure of requests. Understanding these status codes and implementing proper error handling is essential for building robust applications.

​
HTTP Status Codes

​
Success Codes

​
200
OK
Request succeeded. The response body contains the requested data.
​
201
Created
Resource successfully created. Common for POST requests that create new resources.
​
304
Not Modified
Content hasn’t changed since the last request. Used with ETag caching. See Caching for details.

​
Client Error Codes

​
400
Bad Request
The request is malformed or contains invalid parameters. Check your request body, query parameters, and headers.
​
401
Unauthorized
Authentication is required or the provided JWT token is invalid or expired. Include a valid token in the Authorization header.
​
403
Forbidden
The request is authenticated but you don’t have permission to access the resource. This may indicate insufficient privileges.
​
404
Not Found
The requested resource doesn’t exist. Verify the endpoint URL and resource identifiers.
​
429
Too Many Requests
You’ve exceeded the rate limit. Slow down your requests and check the rate limit headers. See Rate Limiting for details.

​
Server Error Codes

​
500
Internal Server Error
The server encountered an unexpected error. Retry your request after a brief delay.
​
502
Bad Gateway
The server received an invalid response from an upstream server. Retry after a delay.
​
503
Service Unavailable
The service is temporarily unavailable. This may occur during maintenance. Retry with exponential backoff.

​
Error Response Format

When an error occurs, the API typically returns a JSON response with error details: 
{
  "error": "Error type or message",
  "message": "Detailed description of what went wrong",
  "statusCode": 400
}
The exact error response format may vary by endpoint. Always check the response body for additional context when debugging errors.

​
Handling Errors

​
Basic Error Handling

import requests

url = "https://frontend-api-v3.pump.fun/coins/{mint}"
headers = {
    "Authorization": "Bearer <your_jwt_token>",
    "Accept": "application/json"
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # Raises HTTPError for bad status codes
    
    data = response.json()
    print("Success:", data)
    
except requests.exceptions.HTTPError as e:
    status_code = e.response.status_code
    
    if status_code == 401:
        print("Authentication failed. Check your JWT token.")
    elif status_code == 403:
        print("Access forbidden. Insufficient permissions.")
    elif status_code == 404:
        print("Resource not found.")
    elif status_code == 429:
        print("Rate limit exceeded. Slow down requests.")
    else:
        print(f"HTTP error occurred: {e}")
        
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

​
Advanced Error Handling with Retries

import requests
import time
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

def create_session_with_retries():
    session = requests.Session()
    
    # Retry on 500, 502, 503, 504 errors
    retry_strategy = Retry(
        total=3,
        status_forcelist=[500, 502, 503, 504],
        backoff_factor=1,  # Wait 1, 2, 4 seconds between retries
        allowed_methods=["GET", "POST"]
    )
    
    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", adapter)
    
    return session

def make_request_with_retry(url, headers, max_attempts=3):
    session = create_session_with_retries()
    
    for attempt in range(max_attempts):
        try:
            response = session.get(url, headers=headers, timeout=10)
            
            if response.status_code == 429:
                # Rate limited - check retry-after header
                retry_after = int(response.headers.get('Retry-After', 60))
                print(f"Rate limited. Waiting {retry_after} seconds...")
                time.sleep(retry_after)
                continue
            
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 401:
                # Authentication error - don't retry
                raise
            elif attempt < max_attempts - 1:
                # Exponential backoff
                wait_time = (2 ** attempt)
                print(f"Request failed. Retrying in {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise
    
    raise Exception("Max retry attempts exceeded")

# Usage
url = "https://frontend-api-v3.pump.fun/coins/{mint}"
headers = {"Authorization": "Bearer <token>", "Accept": "application/json"}

try:
    data = make_request_with_retry(url, headers)
    print("Success:", data)
except Exception as e:
    print(f"Request failed: {e}")

​
Common Error Scenarios

Problem: Your JWT token is missing, invalid, or has expired.Solution:
  • Verify you’re including the Authorization header
  • Check the token format: Bearer <token>
  • Re-authenticate using the /auth/login endpoint to obtain a fresh token
  • Implement automatic token refresh in your application
Problem: Your account doesn’t have permission to access the resource.Solution:
  • Verify your account has the necessary permissions
  • Check if the endpoint requires admin or super admin privileges
  • Contact support if you believe you should have access
Problem: The endpoint or resource doesn’t exist.Solution:
  • Verify the endpoint URL is correct
  • Check that resource identifiers (mint addresses, user IDs) are valid
  • Ensure you’re using the correct API version (v3 is current)
Problem: You’ve sent too many requests in a short period.Solution:
  • Check the x-ratelimit-* response headers for limit information
  • Implement rate limiting in your application
  • Use exponential backoff when retrying
  • See Rate Limiting for best practices
Problem: The server encountered an error or is temporarily unavailable.Solution:
  • Retry the request after a delay
  • Implement exponential backoff (wait 1s, 2s, 4s, etc.)
  • Check the API status page for known issues
  • If errors persist, contact support

​
Best Practices

Always implement proper error handling in production applications. Unhandled errors can lead to poor user experience and application crashes.
  1. Log errors with context - Include the endpoint, request parameters, and timestamp
  2. Retry transient failures - Use exponential backoff for 5xx errors and rate limits
  3. Don’t retry authentication errors - 401 errors require re-authentication, not retries
  4. Handle rate limits gracefully - Respect the Retry-After header
  5. Monitor error rates - Track error patterns to identify systemic issues
  6. Provide user feedback - Display meaningful error messages to end users
  • Authentication - Learn about JWT token management
  • Rate Limiting - Understand rate limits and how to avoid them
  • Caching - Use caching to reduce errors and improve performance

Build docs developers (and LLMs) love

Get started for freeTalk to us