1eye Docs – Buyer Signals API, Webhooks, MCP & Integrations

The 1eye API uses standard HTTP status codes and a consistent JSON error format.

Error response format

All API errors return an error object.

{
  "error": {
    "code": "invalid_parameter",
    "message": "Unknown query parameter: emial.",
    "param": "emial",
    "request_id": "req_359051753366339585"
  }
}

The error object can include:

Field	Description
`code`	Stable, machine-readable error code
`message`	Human-readable description of the error
`param`	The invalid parameter, when applicable
`request_id`	Unique ID for the API request

HTTP status codes

HTTP Status	Error Code	Description
`400 Bad Request`	`invalid_request`	The request is malformed
`400 Bad Request`	`invalid_parameter`	A query parameter or parameter value is invalid
`400 Bad Request`	`invalid_cursor`	The pagination cursor is invalid or does not match the request
`401 Unauthorized`	`authentication_error`	The API key is missing, invalid, or revoked
`404 Not Found`	`not_found`	The requested resource is unavailable to the workspace
`429 Too Many Requests`	`rate_limit_exceeded`	The workspace has exceeded an API rate limit
`500 Internal Server Error`	`internal_error`	An unexpected server error occurred
`503 Service Unavailable`	`service_unavailable`	The API is temporarily unavailable

Invalid request

Malformed requests return:

400 Bad Request

with:

invalid_request

Invalid parameter

Unknown query parameters, invalid values, unsupported sort fields, and other parameter validation errors return:

400 Bad Request

Example:

{
  "error": {
    "code": "invalid_parameter",
    "message": "Unknown query parameter: emial.",
    "param": "emial",
    "request_id": "req_359051753366339585"
  }
}

The 1eye API does not silently ignore unknown query parameters.

Invalid cursor

Malformed, modified, or mismatched pagination cursors return:

400 Bad Request

with:

invalid_cursor

Cursors must be used with the same endpoint, filters, and sorting that were used to generate them.

Authentication errors

A missing, invalid, or revoked API key returns:

401 Unauthorized

Example:

{
  "error": {
    "code": "authentication_error",
    "message": "Invalid or missing API key.",
    "request_id": "req_359051753366339585"
  }
}

Resource not found

If a requested resource does not exist or belongs to another workspace, the API returns:

404 Not Found

with:

not_found

The API does not reveal whether a resource exists in another workspace.

Rate limit errors

When a workspace exceeds an API rate limit, the API returns:

429 Too Many Requests

with:

rate_limit_exceeded

Example:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Workspace API rate limit exceeded. Please retry later.",
    "request_id": "req_359051753366339585"
  }
}

Rate-limited responses may include:

Retry-After: 12

When present, Retry-After indicates how long to wait before retrying the request.

Server errors

Unexpected server errors return:

500 Internal Server Error

with:

internal_error

If the API is temporarily unavailable, it returns:

503 Service Unavailable

with:

service_unavailable

Request IDs

Every API request receives a unique request ID. It is returned in the response header:

X-Request-Id: req_359051753366339585

Error responses also include the same value as error.request_id. Use the request ID when reviewing API Logs or contacting 1eye support about a failed request.

Get Started

Buyers

Signals

Errors

Error response format

HTTP status codes

Invalid request

Invalid parameter

Invalid cursor

Authentication errors

Resource not found

Rate limit errors

Server errors

Request IDs

​Error response format

​HTTP status codes

​Invalid request

​Invalid parameter

​Invalid cursor

​Authentication errors

​Resource not found

​Rate limit errors

​Server errors

​Request IDs

Error response format

HTTP status codes

Invalid request

Invalid parameter

Invalid cursor

Authentication errors

Resource not found

Rate limit errors

Server errors

Request IDs