API Responses and Error Codes

Every Catalog Public GraphQL API call returns an HTTP status and a JSON body. A successful read or write includes a data object. When something fails, details usually appear in an errors array, even when the HTTP status is 200. This guide explains how to read both layers and how to fix common problems.

Use it alongside the Catalog GraphQL API, Using the GraphQL Reference, and Getting Your Catalog API Keys when you debug integrations, scripts, or live requests from the GraphQL reference.

Quick Reference: HTTP Status Codes

Use this table to match an HTTP status to the likely cause and response body shape.

HTTP status	Typical cause	Body shape
200	Request reached GraphQL. Includes successful calls and many failed calls, such as invalid token, permission denied, or business validation.	{ "data": ... } and/or { "errors": [...] }
400	Malformed JSON, invalid GraphQL document with unknown fields, or empty body with Content-Type: application/json	GraphQL errors and/or Fastify JSON error object
404	Wrong URL path, or request blocked before GraphQL, for example when Authorization is missing on some deployments	HTML or JSON Not Found message
405	HTTP method not allowed; use POST	Often empty or minimal
415	Missing or unsupported Content-Type; send application/json	Fastify JSON error object
500	GraphQL syntax error, missing query field, or other failure while building the request context	GraphQL errors, often INTERNAL_SERVER_ERROR

Quick Reference: Error Codes

Look for extensions.code on each entry in errors:

Code	Usually means
UNAUTHENTICATED	Missing, invalid, expired, or revoked API token
FORBIDDEN	Token is valid but not allowed to run this operation, for example a Read Only token on a mutation
ACCESS_DENIED	Account or feature access blocks the operation
BAD_USER_INPUT	Variables or mutation input failed validation
NOT_FOUND	Referenced entity does not exist in your Catalog account
GRAPHQL_VALIDATION_FAILED	Query text does not match the schema, such as an unknown field or argument
INTERNAL_SERVER_ERROR	Query syntax error, malformed request body fields, or unexpected server failure
ERROR_RESULT	Business rule or rate limit; see extensions.payload for more detail

How to Read a Response

Catalog follows standard GraphQL response shape:

• data - Fields you asked for in the query selection set. null at the operation root usually means the call failed.
• errors - One or more problems: auth, validation, permissions, or server errors. Check message and extensions.code.

Treat HTTP status and GraphQL errors as two layers:

1. HTTP status tells you whether the request reached the API and passed basic transport checks: method, JSON body, and content type.
2. errors in the body tells you whether GraphQL execution succeeded. Auth and permission failures often return HTTP 200 with errors, not HTTP 401.

Success check

A call succeeded when HTTP status is 200, errors is absent or empty, and data contains the operation you requested, for example data.getTables.

Example: Successful Query

{
  "data": {
    "getTables": {
      "totalCount": 42,
      "data": [{ "id": "abc123", "name": "FCT_ORDERS" }]
    }
  }
}

Example: Invalid API Token

HTTP status is 200, but the body reports an authentication error:

{
  "errors": [{
    "message": "This API Token is not valid",
    "path": ["getTables"],
    "extensions": {
      "code": "UNAUTHENTICATED"
    }
  }],
  "data": null
}

HTTP Status Details

The following sections expand each HTTP status with common causes and what to check next.

200 OK

200 means the HTTP request was accepted and processed by the GraphQL endpoint. It does not guarantee success.

Situation	What to check
Call worked	errors is missing or empty, and data.<operationName> has the fields you selected
Invalid token	errors[].extensions.code is UNAUTHENTICATED
Wrong token scope	errors[].extensions.code is FORBIDDEN
Bad variables or input	errors[].extensions.code is BAD_USER_INPUT

Always inspect errors before treating 200 as success.

400 Bad Request

The server rejected the request before or during GraphQL validation.

Common cause	What to do
Malformed JSON in the POST body	Validate JSON. Ensure the body is { "query": "...", "variables": { ... } }.
Unknown field or argument in the query	Compare your query to the operation page in the API reference. Remove or rename fields that are not listed under Response.
Empty body with Content-Type: application/json	Send a non-empty JSON object with a query string.

Fastify may return a plain JSON error instead of GraphQL errors, for example:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Body is not valid JSON but content-type is set to 'application/json'"
}

404 Not Found

404 usually means the request never reached the GraphQL handler.

Common cause	What to do
Wrong host or path	Use https://api.castordoc.com/public/graphql for EU or https://api.us.castordoc.com/public/graphql for US. See Base URLs.
Missing Authorization header	Send Authorization: Token <API_TOKEN> on every request. See Authentication.
Wrong ?op= value	Match ?op= to the root field name, for example getTables.

405 Method Not Allowed

Send POST only. GraphQL query strings in a GET URL are not supported on the Public API.

415 Unsupported Media Type

Set both headers on every request:

Content-Type: application/json
Accept: application/json

500 Internal Server Error

Often appears when the GraphQL query text cannot be parsed, for example an empty query, invalid syntax, or a missing query key in the JSON body. The message may start with Context creation failed: followed by a syntax detail.

What to do
Paste the query from the operation Example block and edit incrementally.
Confirm the POST body includes "query": "..." as a JSON string.
See Introduction to GraphQL to validate operation syntax.

GraphQL Error Codes

Each entry in errors includes message and extensions.code. The following sections explain the codes you see most often on the Public API.

UNAUTHENTICATED

Catalog could not authenticate your API token for this request.

You may see this message:

• This API Token is not valid

Likely causes include:

• Token value is wrong or truncated
• Token was rotated or revoked in Settings > API
• Token expired
• Authorization header missing the Token prefix; use Token <value>, not Bearer
• Trial account past its end date

To fix the error:

1. Open Settings > API and confirm the token is still active and not expired.
2. Copy a fresh token if needed. See Getting Your Catalog API Keys for rotation steps.
3. Set the header exactly as Authorization: Token <API_TOKEN>.
4. Confirm your integration uses the correct region, EU versus US. See Base URLs.
5. Update every script, importer, and automation after rotation. Creating a new token for a scope revokes the previous one immediately.

MCP and GraphQL differ

The MCP Integration can return HTTP 401 for bad tokens. The Public GraphQL API returns HTTP 200 with UNAUTHENTICATED in the body instead. Use the same token format, but check errors for GraphQL calls.

FORBIDDEN

Your token authenticated, but it does not have permission for this operation.

You may see this message:

• You do not have the necessary authorization. Min access READ_WRITE

Likely causes include:

• Read Only token used for a mutation, such as create, update, or delete
• Operation requires a higher access level than the token provides

To fix the error:

1. Check the operation badge in the reference: green mut operations need a Read & Write token.
2. Create or switch to a Read & Write token in Settings > API if your workflow writes metadata.
3. Keep Read Only tokens for read-only automation and MCP search use cases.

ACCESS_DENIED

Your account does not have access to the requested feature or resource class.

You may see this message:

• You do not have the necessary access permission. Please contact your administrators.

To fix the error:

1. Confirm the capability is enabled for your Catalog account; some write paths require API beta access.
2. Ask your Catalog administrator or Coalesce Support to verify account settings and entitlements.
3. If you recently changed plans or regions, confirm you are calling the correct API host.

BAD_USER_INPUT

The query reached Catalog, but variables or mutation input failed validation.

Likely causes include:

• Required variable omitted for types marked with ! in the schema
• Wrong JSON type, such as string instead of object, or array shape mismatch
• nbPerPage above the maximum of 500
• page and greaterThanId both set on the same pagination request
• Duplicate IDs in a batch mutation payload
• ID in the payload does not exist in your account

To fix the error:

1. Compare Variables JSON to the operation Arguments section in the reference.
2. Fix types to match the schema: objects for input types, arrays for [Type].
3. For pagination, use either offset with page or cursor with greaterThanId, not both. See Catalog GraphQL API for pagination limits.
4. For batch mutations, ensure every referenced id exists and keys are unique within the payload.

NOT_FOUND

A specific entity referenced in the request does not exist or is not visible in your Catalog account.

To fix the error:

1. Re-run a getter query such as getTables or getColumns to confirm the ID or slug.
2. Confirm you are on the correct region and account; EU and US hosts are separate.
3. Check whether the asset was deleted or never ingested.

GRAPHQL_VALIDATION_FAILED

The query text does not match the published schema.

You may see messages such as:

• Cannot query field "..." on type "Query".
• Unknown argument "..." on field "...".

To fix the error:

1. Open the operation page in the API reference and copy the Example query.
2. Request only fields listed under Response for that operation.
3. Spell operation and argument names exactly as documented; names are case-sensitive.

This error often returns HTTP 400 instead of 200.

INTERNAL_SERVER_ERROR

The server failed while handling the request. The message field has the actionable detail.

Use this table to match common message patterns to fixes:

Message pattern	Likely cause	Fix
Context creation failed: Syntax Error: ...	Invalid GraphQL syntax, empty query, or missing query in the POST body	Fix query text; send a valid query string in JSON
Generic Internal Server Error in extensions.exception	Unexpected failure	Retry once; if it persists, contact Coalesce Support with the operation name, ?op= value, and timestamp

Syntax and context errors may return HTTP 500. Retry after fixing the query; do not assume the API is down until transport errors persist.

ERROR_RESULT

The operation ran, but a business rule blocked the result. Read extensions.payload when present, especially payload.code.

payload.code when present	Meaning	What to do
RateLimitedError	Too many requests in a short window	Back off and retry with exponential delay; reduce call frequency
DuplicatedEmailsError	Duplicate emails in a team or user payload	Deduplicate the emails array
EmailsNotFoundError	Email addresses are not Catalog users	Verify users exist in the account before adding them to a team
AlreadyExistingUsersError	Users are already on the team	Skip existing members or use a different mutation
CircularTermHierarchy	Term parent/child relationship would loop	Fix parent/child IDs in knowledge hierarchy mutations
BulkApplyAllAlreadyRunningError	Another bulk job is already in progress	Wait for the current job to finish, then retry

If payload.code is missing, use the top-level message string and the operation documentation to adjust your input.

Request Checklist

Before opening a support ticket, verify:

1. Method: POST to /public/graphql?op=<operationName>
2. Headers: Content-Type: application/json, Accept: application/json, Authorization: Token <API_TOKEN>
3. Region: EU host api.castordoc.com or US host api.us.castordoc.com matches your Catalog app URL
4. Body: Valid JSON with query and optional variables
5. Success rule: HTTP 200 with no errors and populated data.<operationName>

What's Next?

• Catalog GraphQL API - Authentication, regional base URLs, and operation index
• Using the GraphQL Reference - Send requests from the reference and read the response panel
• Getting Your Catalog API Keys - Create tokens, scopes, and rotation
• Introduction to GraphQL - Query syntax, variables, and selection sets