Skip to main content

​
Error envelope

Every error response follows the same shape: 
{
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "platform and entity_type query params required",
    "request_id": "req_a1b2c3d4e5f6"
  }
}
  • type - a machine-readable error code (e.g., "VALIDATION_ERROR"). Use this for programmatic error handling.
  • message - a human-readable description of what went wrong.
  • request_id - a unique identifier for this request. Quote this in support requests so the team can trace your issue.

​
Response headers

Every response (success or error) includes:
HeaderDescription
X-Request-IDSame value as error.request_id
API-VersionCurrent API version (e.g., 1.0)

​
Content-Type enforcement

All non-GET requests must include Content-Type: application/json. Requests with a different content type receive a 415 UNSUPPORTED_MEDIA_TYPE error before reaching the route handler.

​
Error codes

CodeHTTP StatusWhen it happens
VALIDATION_ERROR400Request body or query params failed schema validation
AUTHENTICATION_ERROR401Missing, invalid, or revoked API key
AUTHORIZATION_ERROR403Valid key but insufficient permissions
NOT_FOUND404Entity, mapping, or resource does not exist
CONFLICT_ERROR409Operation conflicts with existing state
UNSUPPORTED_MEDIA_TYPE415Request Content-Type is not application/json
TRANSFORM_ERROR422Data transformation failed (e.g., missing mapper context)
RATE_LIMIT_ERROR429Too many requests - currently only on POST /demo/session
INTERNAL_ERROR500Unexpected server error - the team is notified
EXTERNAL_SERVICE_ERROR502Upstream service (database) failed

​
Examples

​
401 - Invalid API key

curl "$API_BASE/api/v1/connections" \
 -H "Authorization: Bearer sk_demo_invalid_key"

{
  "error": {
    "type": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key",
    "request_id": "req_x9y8z7w6v5u4"
  }
}

​
400 - Validation error

curl -X POST "$API_BASE/api/v1/connect" \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $API_KEY" \
 -d '{"platform": "invalid"}'

{
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "Invalid input",
    "request_id": "req_m3n4o5p6q7r8"
  }
}

​
404 - Entity not found

curl -X POST "$API_BASE/api/v1/propagate" \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $API_KEY" \
 -d '{
    "format": "platform",
    "platform": "procore",
    "platform_id": "999999999",
    "entity_type": "payment",
    "data": { "notes": "test" }
  }'

{
  "error": {
    "type": "NOT_FOUND",
    "message": "Entity mapping not found",
    "request_id": "req_s1t2u3v4w5x6"
  }
}