Common Error Codes

When you encounter a status code, first identify the type of issue, then troubleshoot by priority

When many people see an error, they immediately suspect the platform is having issues. In reality, most errors during MoleAPI integration can be quickly identified through status codes + configuration items.

Recommended Troubleshooting Approach

Do not throw out your entire configuration right away. It is recommended to check in this order first:

Check the status code first
Determine whether it is an authentication issue, a permission issue, an address issue, or a request content issue
Then go back to the Gateway Console and check the relevant configuration

Quick Reference for Error Codes

Status Code	Common Meaning	What You Should Check First
400	Invalid request parameters	JSON structure, field types, whether the model supports the parameter
401	Authentication failed	Whether the API Key is correct, whether there are extra spaces, whether it has expired
403	Insufficient permissions	Model permissions, Group, IP whitelist, Key limits
404	Invalid address or route	Whether the Base URL is correct, whether `/v1` is missing, whether the path is misspelled
429	Rate limiting or Quota issue	Whether request frequency, concurrency, balance, quota, or limits have been triggered
500	Server-side exception	Retry first and keep the request details; if it persists, contact support

Understanding Each Status Code

400: The Request Itself Has a Problem

This error usually means:

Your request structure is incorrect
A field has the wrong type
You passed a parameter that the model does not support

If you recently switched models, changed SDKs, or copied someone else's sample code, check here first.

401: There Is an Issue with the API Key

Check these first:

Whether you entered an sk-... created in the MoleAPI Gateway Console
Whether there are leading or trailing spaces
Whether the key was copied incompletely
Whether you accidentally pasted a Key from another platform

403: You Can Access the API, but You Do Not Have Permission to Do This

This error is most commonly caused by:

The current Key does not have permission for this model
The current Group does not support this model
An IP whitelist is enabled, but the source IP does not match
The Key's own Quota or limits have been triggered

404: The Address Is Wrong

This is one of the most common issues for beginners.

Check these first:

Whether the Base URL is set to https://api.moleapi.com/v1
Whether you are still sending requests to api.openai.com
Whether you mistakenly entered a full endpoint path as the Base URL

429: You Are Being Limited, or Your Quota Is Insufficient

When you see 429, do not only think "the requests are too fast." Also check:

Whether your balance is insufficient
Whether the Key has limits
Whether concurrency is too high
Whether requests are too frequent in a short period of time

500: Server-Side Exception

If it happens occasionally, retry first. If it is consistently reproducible, it is recommended to keep:

Request time
Model name
Request parameters
Request ID (if available in the client)

This will make follow-up troubleshooting much faster.

A Very Practical Troubleshooting Order

If you do not know where to start, this order will save the most time:

Check the status code
Check the Base URL
Check the API Key
Check the model name
Check the Group / permissions / limits
Check the balance and logs

Rule of thumb

For 404, check the address first; for 401, check the Key first; for 403, check permissions first; for 429, check not only request frequency, but also balance and limits.