Errors

Every error has the shape:

{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "due_date must be a valid ISO-8601 datetime",
    "request_id": "req_6a2918cff58b0a1d387866ee",
    "errors": [{ "field": "due_date", "message": "must be a valid ISO-8601 datetime" }]
  }
}

• type — a stable, broad category.
• code — a stable, machine-readable string.
• request_id — quote this when contacting support. It is generated by Bordio and also returned in the X-Request-Id response header; a value you send in that header is not used as the id.
• errors[] — per-field details for validation failures (present only when relevant).
• details — machine-readable extras for specific codes (present only when relevant), e.g. { "linked_tasks_count": 7 } on tag_in_use.

Catalog

HTTP	type	code	Meaning
401	authentication_error	unauthorized, expired	Missing, invalid, revoked or expired API key.
403	permission_error	insufficient_scope	The key lacks the required access, or the resource is outside its scope.
403	permission_error	key_owner_inactive	The workspace member who created the key is no longer in the workspace. Add them back, or have another member issue a new key.
403	permission_error	workspace_plan_required	The workspace is on a plan that does not include integrations, or its last payment failed. The connection stays — calls start working again once the plan does.
403	permission_error	integrations_unavailable	A personal workspace: integrations are not available there at all, on any plan.
403	permission_error	guest_access_denied	The person who authorised the app is a guest in this workspace. Guests cannot grant integrations access; ask an admin to make them a member.
413	invalid_request_error	payload_too_large	The request body exceeds 256 KB.
404	not_found_error	resource_not_found	The resource does not exist or is not visible to this key.
409	conflict_error	already_exists	The resource already exists, or an Idempotency-Key was reused with a different request body.
409	conflict_error	tag_in_use	DELETE /tags/{id} without force=true on a tag that is linked to tasks; details.linked_tasks_count says how many. Deleted tasks don’t count, archived ones do.
422	validation_error	invalid_request	The request failed validation; see errors[] for the offending fields.
429	rate_limit_error	too_many_requests	Too many requests; retry after the delay in the Retry-After header.
500	api_error	internal_error	Unexpected server error; safe to retry later.
503	api_error	service_overloaded	The server is temporarily overloaded; retry after the delay in the Retry-After header.

Error responses also carry a doc_url pointing back to this page.