Errors & Limits

Elektric returns stable error codes for failures your application can act on. Use the error code to decide what to fix or retry, and keep the Request ID when you need to trace a request.

Limits are enforced for the authenticated project. Your project may have stricter request or spend limits than the platform defaults.

#Error response

{
  "error": {
    "message": "Human-readable explanation",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "request_id": "req_..."
  }
}

Branch on error.code, not message text. request_id may also be returned in the x-elektric-request-id response header.

Streaming and Realtime errors use their respective stream or protocol error formats instead of this HTTP JSON envelope.

#Common errors

Grid may also return operation-specific availability errors such as grid_image_unavailable, grid_video_unavailable, grid_speech_unavailable, or grid_transcription_unavailable when an otherwise supported media operation cannot currently execute. Treat these as conditional retry cases.

More specific validation errors may be returned for files, images, video, speech, transcription, and Realtime. They use the same error.code pattern.

#Retry safely

Retry only when the request is safe to repeat.

Grid may try another eligible route before output begins. Wire does not silently switch models. Once streaming output has started, Elektric does not restart the request with another model.

#Idempotency

Use Idempotency-Key when creating asynchronous video jobs. Reusing the same key for the same project and operation returns the existing job instead of creating another one.

• Maximum length: 200 characters.
• Scope: project and operation.
• Empty keys and keys containing control characters are rejected.

Chat, image generation/editing, speech, transcription, and research do not currently provide the same public idempotent-create guarantee. Retrying those operations after an uncertain failure may repeat provider work and charges.

#Cancellation

Client cancellation stops the client from waiting. It does not necessarily stop upstream provider work.

• AbortSignal stops the client request.
• Ending a stream after work starts may still leave billable provider usage.
• Video jobs support explicit cancellation, but cancellation is best effort.
• Upstream work may still be in flight after cancellation.

#Platform limits

These are platform defaults. Limits are enforced for the authenticated project, and project or account policy may be stricter.

Model-specific context windows, output ceilings, and capabilities vary by model. Check authenticated GET /v1/models for current model information.

#File and media limits

Inline attachments must appear in user messages. Supported inline formats currently include PNG/JPEG/WebP images, MP4 video, and WAV/MPEG/MP4/WebM/OGG/FLAC audio.

#Operation input limits

Video generation duration, aspect ratio, resolution, and other capabilities depend on the selected product. Check Models and Media for current capabilities.

#Check your effective limits

GET /v1/limits returns the limits currently applied to your authenticated project.

{
  "object": "limits",
  "requests_per_minute": 60,
  "burst": { "requests": 20, "window_seconds": 10 },
  "concurrent_requests": 10,
  "daily_request_limit": 10000,
  "monthly_spend_limit_usd": null,
  "current_monthly_spend_usd": "0.000000000"
}

Daily request and monthly spend limits can vary by project.

/v1/limits does not currently include model capabilities, media limits, Realtime limits, file limits, or remaining request capacity.

Temporary uploaded files expire after 1 hour. Generated asset retention varies by operation.

See Models for model-specific capabilities and Grid routing for fallback behavior.