الأخطاء

الأخطاء بصيغة JSON، مثل كل شيء آخر، مع رمز حالة HTTP مطابق ورمز يمكنك التفرّع عليه. الرسالة جملة مخصصة لسجلاتك لا لمستخدميك، وقد تتغير صياغتها، أما الرمز فلن يتغير أبدًا.

غلاف الخطأ

{
  "status": "error",
  "error": {
    "code": "invalid_request",
    "message": "Parameter 'lat' must be a number between -90 and 90.",
    "param": "lat"
  }
}

يكون param موجودًا عندما يتسبب معامل محدد في المشكلة. تُضبط X-Request-Id في استجابات الخطأ أيضًا، فأدرجها إذا تواصلت مع الدعم.

الرموز

HTTP	`code`	متى	ما العمل
400	`invalid_request`	معامل مطلوب مفقود، أو قيمة مشوّهة الصيغة أو خارج النطاق، أو أكثر من 100 نقطة أو عنوان في دفعة واحدة، أو طلب أكثر من 10 نتيجة.	أصلح الطلب. لا تُعد المحاولة دون تغيير.
401	`missing_key`	لم يُرسل أي مفتاح والوصول دون مفتاح معطّل على هذا الخادم. هو مفعّل افتراضيًا، ويُجاب الطلب دون مفتاح ببساطة.	أرسل مفتاحًا في `X-API-Key` أو رمز bearer أو `key=`.
429	`quota_exceeded`	استنفد العنوان طلباته المجانية البالغة 2,500 لليوم دون مفتاح.	انتظر إعادة التصفير (توضح `Retry-After` و`X-Quota-Reset` موعدها)، أو أرسل مفتاحًا يحمل رصيدًا أو باقة Unlimited.
401	`invalid_key`	المفتاح غير موجود.	تحقق من وجود أخطاء إملائية أو نسخ منقوص.
401	`key_revoked`	أُلغي المفتاح من لوحة التحكم.	استخدم مفتاحًا ساريًا.
402	`no_credits`	استُنفدت الحصة المجانية للمفتاح لهذا اليوم ورصيد الحساب فارغ.	أضف رصيدًا من لوحة التحكم، بالبطاقة أو بالعملات المشفرة، أو انتظر إعادة التصفير.
403	`key_ip_limit`	جميع خانات IP لهذا المفتاح تشغلها عناوين أخرى في الفترة القادمة.	استخدم أحد الأجهزة التي تشغل الخانات، أو امنح هذا الجهاز مفتاحه الخاص، أو أضف باقة. راجع خانات IP.
403	`account_suspended`	الحساب موقوف.	تحقق من رسائل البريد الإلكتروني الواردة منا أو افتح تذكرة.
404	`not_found`	المسار غير موجود. الاستعلام الذي لا يطابق شيئًا يعيد `200` مع نتائج فارغة، لا `404`.	تحقق من المسار وبادئة الإصدار.
500	`server_error`	حدث عطل من جانبنا.	أعد المحاولة مرة واحدة بعد ثانية. يُسجَّل الخطأ وينبّهنا. لا يُحتسب.
503	`unavailable`	إحدى الخدمات الخلفية غير متاحة مؤقتًا.	أعد المحاولة مع تأخير متزايد. لا يُحتسب.

أمور ليست أخطاء

لا توجد نتائج. الترميز الجغرافي الأمامي لنص لا معنى له يعيد 200 مع "results": []. والترميز الجغرافي العكسي لنقطة في المحيط يعيد 200 مع "result": null. وكلاهما يُحتسب طلبًا.
دقة منخفضة. النتيجة التي تحمل "precision": "admin" حين كنت تريد منزلًا هي طلب ناجح وجد أقل مما كنت تأمل. تحقق من الحقل.
عناوين IP الخاصة. الاستعلام عن 10.0.0.1 يعيد 200 مع "is_private": true ودون موقع.

الأخطاء على المضيفات البديلة المتوافقة

تعيد مضيفات التوافق الأخطاء بالشكل الذي يستخدمه المزوّد الأصلي، لذا تعمل المعالجة الحالية. على سبيل المثال، يكون الرصيد الفارغ "status": "OVER_QUERY_LIMIT" مع HTTP 200 على gapi.mygeocode.com، و"statusCode": 429 في غلاف Bing على bing.mygeocode.com، و{"status":"fail","message":"quota"} على ipapi.mygeocode.com، أما المفتاح الخاطئ فيكون REQUEST_DENIED و401 وinvalid key على الترتيب. تُرسل ترويسات X-Quota-* على كل مضيف في جميع الأحوال، لذا يمكنك قراءة الحالة الحقيقية من الترويسات إن أردت.

استراتيجية معقولة للتعامل

def call(url, params, tries=3):
    for attempt in range(tries):
        r = session.get(url, params=params, timeout=10)
        if r.status_code == 200:
            return r.json()
        body = r.json()
        code = body["error"]["code"]
        if r.status_code in (500, 503):
            time.sleep(0.2 * (2 ** attempt))
            continue
        # no_credits, key_ip_limit, invalid_request, invalid_key: retrying will not help
        raise ApiError(code, body["error"]["message"], r.headers.get("X-Request-Id"))
    raise ApiError("retries_exhausted", "Gave up after %d attempts" % tries, None)