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 identifier.
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: \"deepseek-ai/DeepSeek-V4-Pro\"",
    "type": "devup_error",
    "code": "missing_model"
  }
}

401

Unauthorized: Invalid API Key

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

Common Causes

Missing Authorization header entirely.
Authorization header does not use the "Bearer" scheme.
API key has been rotated or deleted from the dashboard.
Using an invalid or corrupted key string.

How to Resolve

1.Set the header as: Authorization: Bearer sk-devup-...
2.Regenerate your API key from Dashboard → API Keys.
3.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"
  }
}

401

Unauthorized: Scoped Token Expired

The scoped JWT credential has passed its configured expiration timestamp (exp claim).

Common Causes

The scoped token TTL duration has elapsed.
The client is attempting to reuse an outdated scoped token.

How to Resolve

1.Generate a new scoped token from Dashboard → API Keys.
2.Implement automatic token refresh before the expiration timestamp in your client application.

Example 401 Response

{
  "error": {
    "message": "This scoped token expired at 2026-08-14T10:00:00.000Z.",
    "type": "devup_error",
    "code": "token_expired"
  }
}

401

Unauthorized: Scoped Token Revoked

The scoped JWT credential was explicitly revoked or deactivated by the account owner.

Common Causes

The token was revoked via Dashboard → API Keys.
The token was deactivated due to security or credential rotation.

How to Resolve

1.Generate a new scoped token from Dashboard → API Keys.
2.Check with the account administrator who issued the credential.

Example 401 Response

{
  "error": {
    "message": "This scoped token has been revoked.",
    "type": "devup_error",
    "code": "token_revoked"
  }
}

402

Payment Required: Account Balance Depleted

The authenticated master account lacks sufficient DZD balance to process the request.

Common Causes

DZD balance is zero or below the estimated cost of the request.
Concurrent requests consumed the available pre-paid balance.

How to Resolve

1.Top up your balance via Edahabia or CIB at Dashboard → Billing.
2.Check your balance via GET /v1/user/balance or the dashboard before retrying.

Example 402 Response

{
  "error": {
    "message": "Your balance is depleted. Top up at https://devupai.com/dashboard/billing. Insufficient balance: 0.00 DZD",
    "type": "devup_error",
    "code": "insufficient_balance"
  }
}

402

Payment Required: Scoped Token Budget Exhausted

The scoped token has reached or exceeded its configured lifetime spending limit in DZD.

Common Causes

Total accumulated cost of requests processed with this scoped token reached its budget limit.

How to Resolve

1.Increase the token's budget limit in Dashboard → API Keys.
2.Issue a new scoped token with an updated budget.

Example 402 Response

{
  "error": {
    "message": "Budget exhausted: 50.00 / 50.00 DZD spent.",
    "type": "devup_error",
    "code": "budget_exhausted"
  }
}

403

Forbidden: Account Suspended

The DEVUP account has been suspended by an administrator. All API requests are blocked.

Common Causes

Account flagged for terms of service or security review.
Administrative freeze on the account.

How to Resolve

1.Contact DEVUP AI support at support@devupai.com.

Example 403 Response

{
  "error": {
    "message": "Account suspended. Contact support.",
    "type": "devup_error",
    "code": "account_suspended"
  }
}

403

Forbidden: Model Not Allowed

The scoped token is restricted to specific models and does not grant access to the requested model.

Common Causes

The requested model is not included in the token's allowed models whitelist.
A typo in the requested model identifier when using a restricted scoped token.

How to Resolve

1.Add the requested model to the token's allowed list in Dashboard → API Keys.
2.Change the request payload to specify a whitelisted model.

Example 403 Response

{
  "error": {
    "message": "This scoped token does not grant access to model \"deepseek-ai/DeepSeek-V4-Pro\". Allowed: meta-llama/Llama-3.3-70B-Instruct",
    "type": "devup_error",
    "code": "model_not_allowed"
  }
}

404

Not Found: Model Not Found

The requested model identifier was not found in the catalog or is currently unavailable.

Common Causes

The requested model identifier does not exist in the model catalog.
The model identifier is correct, but the request did not succeed on this attempt.

How to Resolve

1.Verify the model identifier against the model catalog.
2.If the identifier is present in the model catalog, retry the request once before treating the model as unavailable.

Example 404 Response

{
  "error": {
    "message": "The requested model was not found or is unavailable.",
    "type": "devup_error",
    "code": "model_not_found"
  }
}

429

Too Many Requests

Either your account rate limit was reached, or the model is momentarily at capacity. The error message distinguishes the two; honour the Retry-After header.

Common Causes

Exceeded ~100 requests per minute (per account).
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.

Example 429 Response

{
  "error": {
    "message": "This model is currently at capacity. Retry in a few seconds.",
    "type": "devup_error",
    "code": "rate_limit_exceeded"
  }
}

Response Headers

Headers

Retry-After: 5

500

Internal Server Error

An unexpected failure occurred while processing the request.

Common Causes

Inference node timeout or service degradation.
Inference node returned an unexpected response (model overload, quota, outage).
Internal gateway configuration error.
Transient network failure between edge nodes.

How to Resolve

1.Retry after a short delay — most 500s are transient issues.
2.Check the DEVUP status page for ongoing incidents.
3.If the error persists, try a different model (the inference node 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.
401	token_expired	No	Generate a new scoped token or refresh before expiry.
401	token_revoked	No	Generate a new scoped token from Dashboard → API Keys.
402	insufficient_balance	No	Top up master account DZD balance at Dashboard → Billing.
402	budget_exhausted	No	Increase token budget limit or issue a new scoped token.
403	account_suspended	No	Contact DEVUP AI support.
403	model_not_allowed	No	Request an allowed model or update token whitelist.
404	model_not_found	Yes	Verify in catalog; retry once if present.
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