Error Codes

All API errors return a JSON body with a consistent structure. Inspect the code field for machine-readable identification and message for a human-readable description of what went wrong.

Error Response Shape

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "pipeline_id is required",
    "details": {
      "field": "pipeline_id"
    }
  }
}

The details object is present on validation and enrichment errors and provides field-level context. It is absent on errors where no additional detail is available (e.g. INTERNAL_ERROR).

HTTP Status Codes

Status	Code	Meaning
400	`BAD_REQUEST`	Request body is malformed or missing required fields
401	`UNAUTHORIZED`	Missing or invalid authentication credential
402	`PAYMENT_REQUIRED`	Insufficient organization balance
403	`FORBIDDEN`	Valid auth but insufficient permissions, or module not enabled
404	`NOT_FOUND`	Resource does not exist or is not accessible to your org
409	`CONFLICT`	Resource already exists (e.g. member already invited)
410	`GONE`	Resource was deleted or invitation has expired
422	`UNPROCESSABLE_ENTITY`	Validation error (e.g. enrichment not complete, missing context key)
429	`TOO_MANY_REQUESTS`	Rate limit exceeded
500	`INTERNAL_ERROR`	Server-side error; retry with exponential back-off

Common Error Scenarios

Error	Status	How to fix
File enrichment not complete	422	Poll `GET /v2/projects/{id}/files/{fileId}` until `enrichmentStatus: "completed"`
Missing required context key	422	Check the pipeline's `requiredContextKeys`; add the missing keys to your run request
Module not enabled	403	Contact Crowdee to enable `content_verification` or `crowdsourcing` for your org
Insufficient balance	402	Top up via Settings → Billing; check current balance on `GET /v2/organizations/{orgId}`
Invitation expired	410	Re-send the invitation via `POST /v2/organizations/{orgId}/invite`
Resource not found	404	Confirm the ID belongs to your organization; IDs from other orgs are treated as non-existent
Duplicate invite	409	The email address already has a pending invitation or is an existing member

Enrichment error example

If you attempt to start a run before enrichment completes, you receive:

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "File enrichment is not complete",
    "details": {
      "fileId": "file_xyz789",
      "enrichmentStatus": "running"
    }
  }
}

Missing context key example

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Required context key 'claimed_source_url' is missing",
    "details": {
      "requiredKeys": ["claimed_source_url", "claimed_publication_date"],
      "providedKeys": ["claimed_publication_date"]
    }
  }
}

Retrying

Status	Safe to retry?	Strategy
429	Yes	Wait for `Retry-After` seconds, then retry
500	Yes	Exponential back-off starting at 1 second; give up after 5 attempts
502 / 503	Yes	Same as 500
400	No	Fix the request body before retrying
401	No	Re-authenticate; do not retry with the same credential
403	No	Check permissions or contact support
404	No	Verify the resource ID
422	No	Fix the validation error (e.g. wait for enrichment to finish)

The Retry-After header is included in all 429 responses and contains the number of seconds until the rate-limit window resets. Use this value rather than a fixed delay to avoid unnecessary waiting.