Errors and rate limits

PlainField uses standard HTTP status codes and OpenAI-compatible error bodies, so existing OpenAI SDKs and error handling work without changes.

Error response shape

Errors from the chat API (and authentication failures on any endpoint) return an OpenAI-style body:


{
  "error": {
    "message": "Invalid credentials",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Field	Description
`message`	Human-readable description of what went wrong.
`type`	Error category (for example, `invalid_request_error`).
`param`	The offending parameter, when applicable.
`code`	A stable machine-readable code (for example, `invalid_api_key`), when applicable.

The REST API’s own validation errors (/api/logs/:id, etc.) use a simpler body:


{ "error": "log entry not found" }

Status codes

Status	Meaning	Typical cause
`400`	Bad request	Malformed JSON, missing or invalid `model`, or an unsupported parameter.
`401`	Unauthorized	Missing or invalid API key (`code: invalid_api_key`).
`404`	Not found	Unknown route or resource.
`429`	Too many requests	A rate limit was exceeded — see below.
`4xx`	Provider error	The upstream provider rejected the request; its status is passed through.
`5xx`	Server error	An unexpected failure in the gateway or provider.

Rate limits

When a rate limit is exceeded, PlainField responds with 429 Too Many Requests and includes headers describing the limit and when to retry:

Header	Description
`retry-after`	Seconds to wait before retrying.
`x-ratelimit-after`	Seconds until the limit resets.
`x-ratelimit-limit`	Requests allowed in the window.
`x-ratelimit-remaining`	Requests remaining in the window.

Back off for the number of seconds in retry-after, then retry. The OpenAI SDK retries 429 responses automatically with exponential backoff. The specific limits that apply depend on your plan.

Handling errors with the OpenAI SDK


import OpenAI from 'openai'
 
const client = new OpenAI({
  baseURL: 'https://api.plainfield-ai.com/ai',
  apiKey: process.env.PLAINFIELD_API_KEY
})
 
try {
  const response = await client.chat.completions.create({
    model: 'openai/gpt-4o-mini',
    messages: [{ role: 'user', content: 'Hello!' }]
  })
  console.log(response.choices[0].message.content)
} catch (err) {
  // err.status is the HTTP status; err.code maps to the `code` field above.
  console.error(err.status, err.code, err.message)
}

Errors and rate limits

Error response shape

Status codes

Rate limits

Handling errors with the OpenAI SDK

Related