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

Status CodeDescription
200Success - The request completed successfully
201Created - A new resource was created successfully
204No Content - The request succeeded with no response body
400Bad Request - The request was invalid or malformed
401Unauthorized - Authentication failed or missing
403Forbidden - Valid authentication but insufficient permissions
404Not Found - The requested resource doesn’t exist
409Conflict - The request conflicts with existing data
422Unprocessable Entity - Validation errors
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong on our end

​
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

FieldTypeDescription
codestringMachine-readable error code
statusnumberHTTP status code
messagestringBrief human-readable message
descriptionstringDetailed explanation of the error
detailsarrayAdditional error details (for validation errors)

​
Common error codes

​
Authentication errors

CodeStatusDescription
missing_authorization401No authentication credentials provided
invalid_token401The provided token is invalid or expired
insufficient_permissions403Valid credentials but lacking required permissions
missing_scopes403API key doesn’t have required scopes

​
Validation errors

CodeStatusDescription
validation_error422Request body validation failed
invalid_parameters400Query parameters are invalid
missing_required_field422A required field is missing
invalid_field_value422A field contains an invalid value

​
Resource errors

CodeStatusDescription
not_found404The requested resource doesn’t exist
already_exists409A resource with the same identifier already exists
resource_locked423The resource is locked and cannot be modified

​
Rate limiting

CodeStatusDescription
rate_limited429Too many requests in a short period

​
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.