Error handling

The FirstQuadrant API uses conventional HTTP response codes to indicate the success or failure of an API request. This guide explains our error format and how to handle common errors.

​

HTTP status codes

​

Error response format

All errors follow a consistent JSON structure:

{
  "code": "validation_error",
  "status": 422,
  "message": "Validation failed",
  "description": "The request body contains invalid data.",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

​

Error response fields

​

Common error codes

​

Authentication errors

​

Validation errors

​

Resource errors

​

Rate limiting

​

Error handling examples

try {
  const response = await fetch("https://api.us.firstquadrant.ai/v5/contacts", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "FirstQuadrant-Organization-ID": "org_YOUR_ORG_ID",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "invalid-email",
      firstName: "John",
    }),
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.code) {
      case "validation_error":
        console.error("Validation failed:", error.details);
        break;
      case "rate_limited":
        console.error("Rate limit hit, retry after delay");
        break;
      case "missing_authorization":
        console.error("Authentication required");
        break;
      default:
        console.error("API error:", error.message);
    }
  }
} catch (err) {
  console.error("Network error:", err);
}

​

Validation error details

When a validation error occurs, the details array provides specific information about each field that failed validation:

{
  "code": "validation_error",
  "status": 422,
  "message": "Validation failed",
  "description": "The request body contains invalid data.",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "phone",
      "message": "Phone number must include country code"
    },
    {
      "field": "customProperties.industry",
      "message": "Industry must be one of: technology, finance, healthcare"
    }
  ]
}

​

Best practices

1. Always check the response status before attempting to parse the response body
2. Handle rate limiting gracefully by implementing exponential backoff
3. Log error details including the X-Request-Id header for debugging
4. Parse validation errors to provide user-friendly feedback
5. Implement retry logic for transient errors (5xx status codes)
6. Use the error code for programmatic error handling rather than parsing messages

​

Debugging

When reporting issues, include:

• The X-Request-Id header from the response
• The full error response body
• The request method, URL, and headers (excluding sensitive data)
• The request body (if applicable)

This information helps our support team quickly identify and resolve issues.