Troubleshooting Guide
Common issues, debugging techniques, and solutions for Mock API Builder problems.
Quick Diagnostic Checklist
Before You Start Debugging
- Check the Logs tab in your project for error messages
- Verify your dev server is running (npm run dev)
- Ensure you're using the correct endpoint URL
- Confirm your API token is valid (if using authentication)
- Try the request in the built-in API tester first
Common Issues & Solutions
GET /api/proj_abc123/users → 404 Not Found
Possible Causes
- •Wrong project slug: The project ID in the URL doesn't match your actual project
- •Endpoint not created: You haven't set up this endpoint in your project settings
- •Typo in path: The endpoint path has a spelling mistake
- •Wrong HTTP method: Endpoint exists but not for this method (e.g., POST vs GET)
Solutions
1. Verify Project Slug
2. Check Endpoint Configuration
- • Go to Project → Endpoints tab
- • Verify the endpoint path exists (e.g., /users)
- • Ensure the HTTP method is enabled (GET, POST, etc.)
- • Save changes and retry
3. Use Built-in Tester
Go to Project → API Tester to test endpoints without manually typing URLs
GET /api/proj_abc123/users → 401 Unauthorized
Possible Causes
- •Missing API token: Request doesn't include Authorization header
- •Invalid token: API token is expired or incorrect
- •Wrong token format: Not using "Bearer" prefix
- •Endpoint requires auth: This endpoint is configured to require authentication
Solutions
1. Get Your API Token
- • Go to Profile → API Tokens
- • Create a new token or copy existing one
- • Make sure the token has access to this project
2. Include Token in Request
3. Disable Auth (for testing)
Go to Project → Settings → Authentication → Toggle off "Require authentication"
Access to fetch at 'http://localhost:3000/api/...' has been blocked by CORS policy
What is CORS?
Cross-Origin Resource Sharing (CORS) is a browser security feature that restricts web pages from making requests to a different domain than the one that served the page.
Solutions
1. Mock API Builder Handles CORS Automatically
All API endpoints automatically include CORS headers. This error usually means a different issue.
2. Check Your Request URL
3. For Production Deployments
If deploying Mock API Builder, configure allowed origins:
- • Go to Project → Settings → Security
- • Add your frontend domain to "Allowed Origins"
- • Or use "*" to allow all origins (dev only)
SyntaxError: Unexpected token < in JSON at position 0
Possible Causes
- •Receiving HTML instead of JSON: Often happens with 404 or 500 errors
- •Malformed JSON in schema: Schema definition has syntax errors
- •Wrong Content-Type: Response not marked as application/json
Solutions
1. Check Response Status Code
2. Validate Your Schema
- • Go to Project → Endpoints → Edit schema
- • Use the built-in JSON validator
- • Check for missing commas, quotes, or brackets
- • Test schema at jsonlint.com
3. Check Logs for Errors
The Logs tab will show if there's an error generating mock data from your schema
HTTP 429 - Rate limit exceeded. Retry after 60 seconds
What Happened?
You've made too many requests in a short time period. Rate limiting prevents abuse and ensures fair usage.
Solutions
1. Wait and Retry
2. Check Rate Limit Headers
3. Adjust Rate Limits (Project Owner)
- • Go to Project → Settings → Rate Limiting
- • Increase requests per minute (default: 100)
- • Or disable rate limiting for development
4. Implement Request Throttling
Add delays between requests or use request batching to stay under limits
API responses taking longer than 500ms or timing out
Common Causes
- •Too many mock records: Generating 10,000+ records takes time
- •Complex nested schemas: Deep object nesting slows generation
- •Database connection issues: Slow queries or connection timeouts
- •No pagination: Returning entire dataset in one request
Solutions
1. Reduce Mock Data Count
2. Simplify Schema
3. Enable Caching
- • Go to Project → Settings → Performance
- • Enable response caching (cache generated data)
- • Set cache TTL (e.g., 60 seconds)
4. Check Database Status
View Logs tab for database connection errors or slow query warnings
5. Monitor Performance
Debugging Techniques
Network Tab
- • View all API requests
- • Check request/response headers
- • Inspect response body
- • See timing breakdown
Console Tab
- • Log request details
- • View error stack traces
- • Test fetch() directly
Every request is logged with details:
- • Timestamp
- • HTTP method and path
- • Status code
- • Response time
- • Request headers/body
- • Error messages
→ Project → Logs tab
Eliminate browser variables by testing from command line:
Built-in tester helps isolate issues:
- • Pre-configured project endpoints
- • Automatic auth token inclusion
- • Formatted JSON responses
- • Response headers visible
- • No CORS or browser issues
→ Project → API Tester tab
Understanding Error Responses
All errors from Mock API Builder follow a consistent JSON format:
Common Error Codes
| Code | Status | Meaning |
|---|---|---|
| INVALID_REQUEST | 400 | Request data is malformed or invalid |
| UNAUTHORIZED | 401 | Missing or invalid authentication |
| FORBIDDEN | 403 | No permission to access resource |
| NOT_FOUND | 404 | Resource doesn't exist |
| VALIDATION_ERROR | 422 | Data failed validation rules |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests |
| INTERNAL_ERROR | 500 | Server error occurred |
Example Error Response
Still Need Help?
Browse our comprehensive guides:
Learn from working examples:
Step-by-step guides for common use cases
See frequently asked questions:
Answers to common questions and issues
Still stuck? We're here to help:
• Email: support@mockapi.dev
• GitHub Issues (for bugs)
• Discord Community