GST Filing Details Error Codes

Business
POST /api/v1/gst/filing-details Bearer

How GST Filing Details reports failures. Branch on message_code and charged, not on the HTTP status — 422 is sent both for input we rejected (free) and for a lookup the provider ran and billed us for.

Endpoint Error Response — 422 

{
    "status": "SUCCESS",
    "status_code": 422,
    "charged": true,
    "success": false,
    "message": "Invalid GSTIN",
    "message_code": "VERIFICATION_FAILED",
    "order_id": "W2A1739512345abcdef01",
    "data": {
        "order_id": "W2A1739512345abcdef01",
        "error_code": "INVALID_GSTIN",
        "result": {
            "gst_number": "03DOXPM4071K1ZZ",
            "financial_year": "2023-24",
            "filing_count": 0,
            "filings": []
        }
    }
}

HTTP Status Codes

Code Status Charged Description
200 OK Yes Verification result returned
202 Accepted Yes Accepted and being processed, or the provider did not respond in time — check message_code to tell the two apart, and quote the order_id
400 Bad Request No Verification failed or invalid vendor response
401 Unauthorized No Missing or invalid API key
402 Payment Required No Insufficient balance — recharge required
403 Forbidden No No access to this API service
422 Unprocessable Entity Depends — read charged Either input validation failed (not charged), or the provider ran the lookup and returned a negative result (charged). message_code distinguishes them: INVALID_INPUT vs VERIFICATION_FAILED / NO_RECORD_FOUND
429 Too Many Requests No Rate limit exceeded
404 Not Found No Unknown endpoint
500 Internal Server Error No Unexpected error on our side
503 Service Unavailable No Vendor temporarily unavailable

When You Are Charged

message_code Charged HTTP status What it means
OK Yes 200 SUCCESS Verified. The provider ran the lookup and returned a result.
ACCEPTED Yes 202 PENDING Queued at the provider. Quote the order_id to collect the result.
PROVIDER_NO_RESPONSE Yes 202 PENDING The provider did not respond in time. Held for manual review — not auto-refunded.
VERIFICATION_FAILED Yes 422 SUCCESS The provider ran the lookup and the details did not verify. The work was done, so the call is billed.
NO_RECORD_FOUND Yes 422 SUCCESS The provider ran the lookup and found no matching record. Billed for the same reason.
SOURCE_UNAVAILABLE Yes 422 SUCCESS The provider accepted and ran the lookup, but the underlying record source was down and could not answer. The provider bills us for the attempt, so the call is billed. Retry shortly.
INVALID_INPUT No 422 FAILED Your parameters were rejected before any call was placed.
REQUEST_FAILED No 400 FAILED The call was placed and failed definitively. Refunded to your wallet automatically.
MISSING_API_KEY No 401 FAILED No API key on the request.
INVALID_API_KEY No 401 FAILED Key invalid or expired, or the calling IP is not allowed.
INSUFFICIENT_BALANCE No 402 FAILED Your wallet balance is below the price of this call.
NO_API_ACCESS No 403 FAILED Your account is not subscribed to this API.
NOT_FOUND No 404 FAILED No such endpoint.
RATE_LIMITED No 429 FAILED Per-key, per-service one-minute limit exceeded.
INTERNAL_ERROR No 500 FAILED Unexpected error on our side.
PROVIDER_UNAVAILABLE No 503 FAILED The service could not be reached.

Common Error Responses

Every response carries charged. On all of the errors below it is false — the call never reached the provider, so nothing was billed. The absence of an order_id means the same thing. 

// 401 — MISSING_API_KEY
{
    "status": "FAILED",
    "status_code": 401,
    "charged": false,
    "success": false,
    "message": "API key is required.",
    "message_code": "MISSING_API_KEY"
}
// 401 — INVALID_API_KEY
{
    "status": "FAILED",
    "status_code": 401,
    "charged": false,
    "success": false,
    "message": "Invalid, expired, or IP-restricted API key.",
    "message_code": "INVALID_API_KEY"
}
// 402 — INSUFFICIENT_BALANCE
{
    "status": "FAILED",
    "status_code": 402,
    "charged": false,
    "success": false,
    "message": "Insufficient balance. Please recharge your account.",
    "message_code": "INSUFFICIENT_BALANCE"
}
// 403 — NO_API_ACCESS
{
    "status": "FAILED",
    "status_code": 403,
    "charged": false,
    "success": false,
    "message": "You do not have access to this API service.",
    "message_code": "NO_API_ACCESS"
}
// 422 — INVALID_INPUT
{
    "status": "FAILED",
    "status_code": 422,
    "charged": false,
    "success": false,
    "message": "The request could not be accepted. Check the parameters and try again.",
    "message_code": "INVALID_INPUT"
}
// 429 — RATE_LIMITED
{
    "status": "FAILED",
    "status_code": 429,
    "charged": false,
    "success": false,
    "message": "Rate limit exceeded. Please try again later.",
    "message_code": "RATE_LIMITED"
}
// 503 — PROVIDER_UNAVAILABLE
{
    "status": "FAILED",
    "status_code": 503,
    "charged": false,
    "success": false,
    "message": "Service temporarily unavailable.",
    "message_code": "PROVIDER_UNAVAILABLE"
}