Error Handling

Understanding VibeMap API error responses.

Robust error handling is essential for a reliable integration. The VibeMap API uses standard HTTP status codes and provides detailed JSON error objects to help you debug and recover.

Error Response Format

When an error occurs, the API returns a response body in the following format:

{
  "error": "Short description of the error",
  "details": {
    "field": "Optional specific technical details or validation messages"
  }
}

Handling Validation Errors (400)

We use strict Zod-based validation on all input data. If you receive a 400 Bad Request, check the details field for a breakdown of which fields failed validation.

Common reasons for 400 errors:

• Missing required fields (e.g., project_id).

• Invalid UUID formats.

• Invalid enum values (e.g., status must be draft, active, or archived).

---

Partial Success in Batch Operations (207)

One unique aspect of the VibeMap API is the 207 Multi-Status response. This is used during batch operations where some items might succeed while others fail.

Example 207 Response

{
  "success": true,
  "results": [
    { "id": "uuid-of-successful-item", "name": "Success" }
  ],
  "errors": [
    {
      "error": "Validation failed",
      "item": { "data": { "name": "" } },
      "details": { "name": { "_errors": ["Persona name is required"] } }
    }
  ],
  "meta": {
    "total": 2,
    "successful": 1,
    "failed": 1
  }
}

Best Practice for 207s

Always check the meta.failed count. If it's greater than 0, iterate through the errors array to identify which specific items need to be corrected and retried.

---

Handling Rate Limits

If you exceed our usage thresholds, the API will return a 429 Too Many Requests status.

• Retry Strategy: We recommend using Exponential Backoff. Start with a small delay (e.g., 1 second) and double it for each subsequent retry.

• Avoid Parallel Bursts: Instead of sending 100 requests at once, use the Batch API or space out your requests.

Authentication Failures (401/403)

• 401 Unauthorized: Your token is missing, invalid, or expired.

• 403 Forbidden: Your token is valid, but you do not have permission to access the specific resource (e.g., trying to access a project belonging to another user).