Account & Security

API Error Reference

Every error returned by the DEVUP AI Gateway follows the OpenAI-compatible error format. This page documents every status code, its causes, and how to resolve it.

Standard Error Response Shape

All error responses from the gateway are JSON objects with a top-level error key. The shape is intentionally compatible with the OpenAI error format so existing SDK error handlers work out of the box.

Response Body

{
  "error": {
    "message": "Human-readable description of the error.",
    "type": "devup_error",
    "code": "machine_readable_error_code"
  }
}

Field	Type	Description
error.message	string	Human-readable explanation of the error. Safe to display to end users.
error.type	string	Always `"devup_error"` for gateway-originated errors.
error.code	string	Machine-readable error code. Use this for programmatic error handling in your client.

Rate Limit Response Headers

When you receive a 429 response, these headers are included to help you implement backoff logic:

Header	Description
X-RateLimit-Limit	Maximum number of requests allowed in the current window.
X-RateLimit-Remaining	Number of requests remaining in the current window.
X-RateLimit-Reset	Unix timestamp (ms) when the current window resets.
Retry-After	Seconds to wait before retrying the request.

Error Code Directory

Detailed reference for every error the DEVUP AI Gateway can return.

400

Bad Request

The request payload could not be parsed or is missing required fields. This includes malformed JSON, absent model identifiers, or unsupported parameter values.

Common Causes

Request body is not valid JSON (syntax error, trailing comma, unquoted keys).
The required "model" field is missing or not a string.
Unsupported parameters for the target model (e.g., sending tools to a non-tool-calling model).
Invalid value types (e.g., temperature as a string instead of a number).

How to Resolve

1.Validate your JSON payload with a linter before sending.
2.Ensure the "model" field is present and matches a supported DevUp model alias.
3.Refer to the model's documentation page for supported parameters.
4.Check Content-Type is set to application/json.

Example 400 Response

{
  "error": {
    "message": "The \"model\" field is required. Example: \"devup-llama-3\"",
    "type": "devup_error",
    "code": "missing_model"
  }
}

401

Unauthorized

The request did not include a valid API key, or the provided key has been deactivated or revoked.

Common Causes

Missing Authorization header entirely.
Authorization header does not use the "Bearer" scheme.
API key has been rotated or deleted from the dashboard.
Scoped JWT token has been explicitly revoked.
Using a key from a different environment (e.g., test key in production).

How to Resolve

1.Set the header as: Authorization: Bearer sk-devup-...
2.Regenerate your API key from Dashboard → API Keys.
3.If using scoped tokens, verify the token has not been revoked.
4.Ensure there are no trailing whitespace or newline characters in the key.

Example 401 Response

{
  "error": {
    "message": "The API key provided is invalid or has been deactivated.",
    "type": "devup_error",
    "code": "invalid_api_key"
  }
}

403

Forbidden

The authenticated account lacks sufficient DZD balance to process the request, or a scoped token is attempting to access a model outside its whitelist.

Common Causes

DZD balance is zero or insufficient for the estimated cost of the request.
Account has been suspended by an administrator.
Scoped token does not include the requested model in its allowed models list.
Scoped token budget has been fully exhausted.

How to Resolve

1.Top up your balance via Edahabia or CIB at Dashboard → Billing.
2.If using scoped tokens, add the model to the token's allowed list or use a wildcard.
3.Check your current balance via the dashboard before retrying.
4.Contact support if you believe your account was suspended in error.

Example 403 Response

{
  "error": {
    "message": "Your balance is depleted. Top up at https://devup.ai/billing.",
    "type": "devup_error",
    "code": "insufficient_balance"
  }
}

429

Too Many Requests

The request was rejected because the per-key or per-IP rate limit has been exceeded. DevUp enforces a sliding-window rate limiter.

Common Causes

Exceeded ~200 requests per minute (per API key).
Exceeded ~20 requests per minute (per IP, unauthenticated).
Burst traffic from automated scripts or load tests without throttling.

How to Resolve

1.Implement exponential backoff with jitter in your client.
2.Respect the Retry-After header returned in the response.
3.Use a token-bucket or leaky-bucket algorithm for batch workloads.
4.Request a rate limit increase via Dashboard → Account.

Example 429 Response

{
  "error": {
    "message": "Rate limit exceeded. Please slow down your requests and try again shortly.",
    "type": "devup_error",
    "code": "rate_limit_exceeded"
  }
}

Response Headers

Headers

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716000000000
Retry-After: 12

500

Internal Server Error

An unexpected failure occurred within the DevUp Gateway or the upstream inference provider was unreachable or returned an error.

Common Causes

Upstream provider timeout or service degradation.
Upstream provider returned a non-2xx response (model overload, quota, outage).
Internal gateway configuration error (e.g., missing upstream API key).
Transient network failure between DevUp edge and upstream.

How to Resolve

1.Retry after a short delay — most 500s are transient upstream issues.
2.Check the DevUp status page for ongoing incidents.
3.If the error persists, try a different model (the upstream for that specific model may be down).
4.Contact support with your request ID if the issue continues.

Example 500 Response

{
  "error": {
    "message": "DEVUP AI Gateway Error",
    "type": "devup_error",
    "code": "GATEWAY_TIMEOUT"
  }
}

Quick Reference

Status	Code	Retryable	Action
400	invalid_request_body	No	Fix the request payload.
401	invalid_api_key	No	Regenerate or correct your API key.
403	insufficient_balance	No	Top up DZD balance.
429	rate_limit_exceeded	Yes	Wait for Retry-After, then retry.
500	GATEWAY_TIMEOUT	Yes	Retry with backoff; try a different model.

Rate Limits

Webhooks