Errors Endpoint

Report a new error to Checkend. The error will be grouped with similar errors based on its fingerprint.

Request Headers

Request Body

{
  "error_class": "string (required)",
  "error_message": "string (required)",
  "backtrace": ["string"],
  "context": {},
  "request": {
    "url": "string",
    "method": "string",
    "params": {},
    "headers": {}
  },
  "user_info": {
    "id": "string",
    "email": "string",
    "name": "string"
  },
  "fingerprint": "string"
}

Example Request

curl -X POST https://checkend.example.com/ingest/v1/errors \
  -H "Content-Type: application/json" \
  -H "Checkend-Ingestion-Key: ck_live_abc123" \
  -d '{
    "error_class": "NoMethodError",
    "error_message": "undefined method foo for nil:NilClass",
    "backtrace": [
      "app/models/user.rb:42:in validate_email",
      "app/controllers/users_controller.rb:15:in create"
    ],
    "context": {
      "rails_env": "production"
    }
  }'

Response

Success (201 Created)

Returned when a new notice is created.

{
  "id": 12345,
  "problem_id": 789,
  "deduplicated": false,
  "occurrence_count": 1
}

Deduplicated (200 OK)

Returned when an identical error was recently reported. No new notice is created, but the occurrence is counted. See Notice Deduplication for details.

{
  "problem_id": 789,
  "deduplicated": true,
  "occurrence_count": 5
}

Error (422 Unprocessable Entity)

{
  "error": "error.class is required"
}

Rate Limited (429 Too Many Requests)

Response includes a Retry-After header with seconds until the limit resets.

{
  "error": "Rate limit exceeded. Retry after 45 seconds."
}

Response Codes

Rate Limiting

The ingestion API is rate limited per ingestion key to protect your Checkend instance from being overwhelmed during error spikes.

Rate limits are applied per ingestion key, so each app has its own quota. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating when you can retry.

Notice Deduplication

Checkend automatically deduplicates identical errors within a configurable time window (default: 60 seconds) to protect against error loops flooding your database.

When an identical error is detected:

• The API returns 200 OK instead of 201 Created
• The response includes deduplicated: true and the total occurrence_count
• No new notice record is created, but the occurrence is still counted

For configuration options and more details, see the Notice Deduplication guide.