Error Handling

The Qarta API uses standard HTTP status codes and error responses to help you debug issues.

HTTP Status Codes

Code	Meaning
200	OK - Request succeeded
400	Bad Request - Invalid request parameters or malformed request body
401	Unauthorized - Missing or invalid API key
403	Forbidden - Insufficient permissions for the requested resource
500	Internal Server Error - Server-side error

Error Response Format

Depending on the endpoint, error responses follow one of these formats:

Format 1: Simple Message Response

{
  "message": "Error description"
}

Format 2: Nested Message Response

{
  "errorMessage": {
    "message": "Error description"
  }
}

Which endpoints use which format?

Endpoint Category	Error Format
Portfolio endpoints (accumulation, entries, points, provision)	Nested: { "errorMessage": { "message": "..." } }
Risk report endpoints (point risk, point-buffer risk)	Simple: { "message": "..." }
Location endpoints (geocode, autocomplete, reverse geocode)	Simple: { "message": "..." }
Enrichment endpoints (single, batch)	Simple: { "message": "..." }
WMS / WFS endpoints	OGC XML error responses or simple JSON { "message": "..." }

Handling both formats

To safely extract the error message from any Qarta endpoint, check for both formats:

function getErrorMessage(body) {
  return body?.errorMessage?.message || body?.message || 'Unknown error';
}

Common Error Scenarios

400 Bad Request

Cause: Invalid request parameters or malformed request body

Example:

{
  "errorMessage": {
    "message": "Invalid parameter format"
  }
}

Solutions:

• Verify all required parameters are provided
• Check that parameter types match the API specification
• Ensure the request body is valid JSON
• Validate that filter expressions and spatial queries are properly formatted

401 Unauthorized

Cause: Missing or invalid API key

Solutions:

• Verify your API key is correct
• Ensure the Authorization header is included with your API key
• Check that the API key hasn't been revoked in your dashboard
• Confirm the API key has access to the requested resource

403 Forbidden

Cause: Your API key doesn't have permission to access the requested resource

Example scenarios:

• Accessing a portfolio you don't have permission to view
• Attempting to query data sources not available to your account

Solutions:

• Check your account permissions in the dashboard
• Verify the API key has access to the portfolio or data source
• Contact support if you believe you should have access

500 Internal Server Error

Cause: Server-side error

Solutions:

• Retry the request after a short delay
• Implement exponential backoff for automatic retries
• If the error persists, contact support with details about the request

Retry Strategy

For transient errors (5xx status codes), implement exponential backoff:

async function retryRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) {
        return response;
      }
      if (response.status >= 500 && i < maxRetries - 1) {
        // Retry on server errors
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Debugging Tips

• Check the HTTP status code first to determine the error type
• Review the error message for specific details about what went wrong
• Verify your API key and request parameters
• For 500 errors, try again after a brief delay
• Contact support if you encounter persistent errors