Error Codes & Troubleshooting

This page documents common error responses from ZodBack public APIs and how to resolve them.

HTTP Status Codes

200 OK

Request succeeded. Response body contains the requested data.

400 Bad Request

The request was malformed. Common causes:

• Missing required query parameters
• Invalid JSON in request body
• Invalid field values

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    { "field": "title", "message": "title must be at least 1 character" }
  ]
}

401 Unauthorized

Authentication failed. Causes:

• Missing Authorization header
• Invalid or expired API token
• Malformed token format

Fix: Check your token is valid and the header format is Bearer <token>.

403 Forbidden

Access denied. Causes:

• Token doesn't have access to the requested project
• CORS origin not in token's allowed origins
• Attempting to access a non-public resource

Fix: Verify the token belongs to the correct project and allowed origins include your domain.

404 Not Found

Resource doesn't exist. Causes:

• Invalid slug or ID
• Page is not published or not public
• Space doesn't exist or is private

Fix: Verify the resource exists, is published, and is marked as public.

429 Too Many Requests

Rate limit exceeded. The API limits requests per token.

Fix: Implement client-side caching to reduce API calls. The portal template includes built-in caching.

500 Internal Server Error

Server-side error. This is a bug.

Fix: Report the issue with the request details and error response.

Common Issues

"Failed to fetch" in browser

This is usually a CORS error. Check:

1. Your domain is in the token's allowed origins
2. The API server is running and accessible
3. The URL path is correct

Data not updating

Public endpoints use server-side caching (5 minutes by default). The portal template also caches responses client-side. To force a refresh:

• Wait for the cache TTL to expire
• Clear browser cache / hard refresh
• In the portal, the cache duration is configurable in config.js

Pages not appearing in portal

Ensure the page meets all criteria:

• Status: Must be published (not draft or archived)
• Public: Must have isPublic: true
• Space: Must belong to a public space

Search returning no results

• Minimum query length is usually 2 characters
• Search indexes are updated when pages are created/updated
• Only published, public pages are searchable via public endpoints

Debug Mode

Enable debug logging in the portal by setting:

// In js/config.js
DEBUG: true,

This logs API requests and errors to the browser console.

Getting Help

• Check the dashboard logs at Settings > Logs
• Review the API documentation at /docs/api in the dashboard
• Contact the platform administrator for server-side issues