Troubleshooting & FAQs

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
Check which Environment is active (Dev, Staging, Prod)
Check which Environment is active (Dev, Staging, Prod)
Confirm your API token is valid (if using authentication)
Try the request in the built-in API tester first

Common Issues & Solutions

404 Not Found - Endpoint Doesn't Exist

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

http

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

401 Unauthorized - Authentication Failed

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

bash

3. Disable Auth (for testing)

Go to Project → Settings → Authentication → Toggle off "Require authentication"

CORS Errors - Cross-Origin Request Blocked

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

plaintext

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)

Invalid JSON Response

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

javascript

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

429 Too Many Requests - Rate Limit Exceeded

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

javascript

2. Check Rate Limit Headers

plaintext

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

Slow Response Times / Performance Issues

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

json

2. Simplify Schema

json

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

plaintext

Stateful Mocking Issues

Data isn't persisting after POST/PUT requests

Possible Causes

•Feature disabled: Stateful mocking is not enabled for this endpoint
•Wrong State Key: Endpoint is writing to a different key than you're reading from
•Server Restart: In-memory state clears when the dev server restarts

Solutions

1. Enable Stateful Mocking

json

2. Check State Keys

Ensure POST (write) and GET (read) endpoints use the exact same stateKey (e.g., "users").

Environment Issues

Getting wrong data or variables not resolving

Possible Causes

•Wrong Environment: Request is hitting the default environment instead of the specific one
•Missing Variable: Variable is defined in Dev but not in Prod

Solutions

1. Specify Environment

bash

2. Check Variable Syntax

Use {{env.variableName}} in your schema or mock data.

Debugging Techniques

Use Browser DevTools

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

Check Application Logs

Every request is logged with details:

• Timestamp
• HTTP method and path
• Status code
• Response time
• Request headers/body
• Error messages

→ Project → Logs tab

Test with cURL

Eliminate browser variables by testing from command line:

bash

Use Built-in API Tester

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

Standard Error Format

All errors from Mock API Builder follow a consistent JSON format:

json

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

json

Still Need Help?

Check the Documentation

Browse our comprehensive guides:

→ Learning Center Home → Getting Started Guide → HTTP Status Codes Reference

View Example Projects

Learn from working examples:

→ Tutorial Projects

Step-by-step guides for common use cases

Common Questions

See frequently asked questions:

→ FAQ Section

Answers to common questions and issues

Contact Support

Still stuck? We're here to help:

• Email: support@mockapibuilder.io

• GitHub Issues (for bugs)

• Discord Community

Troubleshooting Best Practices

Check logs first: Most issues are visible in request logs

Test in isolation: Use built-in API tester before frontend integration

Verify credentials: Ensure API tokens are valid and have correct permissions

Check status codes: They tell you exactly what went wrong

Use browser DevTools: Network tab shows complete request/response details

Simplify when debugging: Remove complexity to isolate the problem

Test with cURL: Eliminates browser-specific issues

Monitor performance: Use logs to track response times

Read error messages: They usually tell you exactly what's wrong

Compare with examples: Check tutorial projects for reference implementations

Previous: Performance Optimization Next: Frequently Asked Questions

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
Check which Environment is active (Dev, Staging, Prod)
Check which Environment is active (Dev, Staging, Prod)
Confirm your API token is valid (if using authentication)
Try the request in the built-in API tester first

Common Issues & Solutions

404 Not Found - Endpoint Doesn't Exist

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

http

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

401 Unauthorized - Authentication Failed

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

bash

3. Disable Auth (for testing)

Go to Project → Settings → Authentication → Toggle off "Require authentication"

CORS Errors - Cross-Origin Request Blocked

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

plaintext

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)

Invalid JSON Response

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

javascript

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

429 Too Many Requests - Rate Limit Exceeded

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

javascript

2. Check Rate Limit Headers

plaintext

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

Slow Response Times / Performance Issues

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

json

2. Simplify Schema

json

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

plaintext

Stateful Mocking Issues

Data isn't persisting after POST/PUT requests

Possible Causes

•Feature disabled: Stateful mocking is not enabled for this endpoint
•Wrong State Key: Endpoint is writing to a different key than you're reading from
•Server Restart: In-memory state clears when the dev server restarts

Solutions

1. Enable Stateful Mocking

json

2. Check State Keys

Ensure POST (write) and GET (read) endpoints use the exact same stateKey (e.g., "users").

Environment Issues

Getting wrong data or variables not resolving

Possible Causes

•Wrong Environment: Request is hitting the default environment instead of the specific one
•Missing Variable: Variable is defined in Dev but not in Prod

Solutions

1. Specify Environment

bash

2. Check Variable Syntax

Use {{env.variableName}} in your schema or mock data.

Debugging Techniques

Use Browser DevTools

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

Check Application Logs

Every request is logged with details:

• Timestamp
• HTTP method and path
• Status code
• Response time
• Request headers/body
• Error messages

→ Project → Logs tab

Test with cURL

Eliminate browser variables by testing from command line:

bash

Use Built-in API Tester

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

Standard Error Format

All errors from Mock API Builder follow a consistent JSON format:

json

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

json

Still Need Help?

Check the Documentation

Browse our comprehensive guides:

→ Learning Center Home → Getting Started Guide → HTTP Status Codes Reference

View Example Projects

Learn from working examples:

→ Tutorial Projects

Step-by-step guides for common use cases

Common Questions

See frequently asked questions:

→ FAQ Section

Answers to common questions and issues

Contact Support

Still stuck? We're here to help:

• Email: support@mockapibuilder.io

• GitHub Issues (for bugs)

• Discord Community